Installation

Requirements

Requirement	Version	Notes
Python	3.12+	Required
Docker	20.10+	Required for sandbox tools
uv	Latest	Recommended package manager

Install from Source

1. Clone the repository

   git clone https://github.com/dcramer/ash.git
   cd ash

2. Install dependencies

   uv sync --all-groups

3. Verify CLI

   uv run ash --help

Bootstrap Configuration

Create a starter config:

uv run ash init

By default this writes ~/.ash/config.toml (or $ASH_HOME/config.toml when ASH_HOME is set).

Inspect what is currently configured:

uv run ash config show

Validate config:

uv run ash config validate

Recommended Auth Path (OAuth)

Authenticate with OpenAI OAuth:

uv run ash auth login

Use openai-oauth providers in your model aliases:

[models.default]
provider = "openai-oauth"
model = "gpt-5.2"

[models.codex]
provider = "openai-oauth"
model = "gpt-5.2-codex"

Check auth status:

uv run ash auth status

Note

OAuth credentials are stored in ~/.ash/auth.json.

Alternative Auth Path (API Key)

[openai]
api_key = "sk-..."

[models.default]
provider = "openai"
model = "gpt-5.2"

Run Upgrade (Builds Sandbox)

uv run ash upgrade

If you need to rebuild sandbox artifacts manually:

uv run ash sandbox build

Start Chat

uv run ash chat

Uninstall / Cleanup

For full removal (service, sandbox artifacts, Ash data, and optional install cleanup), see:

• Uninstall

Troubleshooting

Config not found

Run:

uv run ash init

OAuth missing

Run:

uv run ash auth login

Docker unavailable

Check:

docker info