Installation

Requirements

Requirement	Version	Notes
Python	3.12+	Required
Docker	20.10+	For sandbox execution
uv	Latest	Recommended package manager

API Keys

Ash requires two API keys for the full experience:

Provider	Purpose	Get a key
Anthropic	LLM (Claude powers the chat)	console.anthropic.com
OpenAI	Memory embeddings (semantic search)	platform.openai.com

Install from Source

Clone the repository

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

Install with uv
Terminal window
```
uv sync --all-groups
```
Verify installation
Terminal window
```
uv run ash --help
```

Configuration

Create your configuration file:

uv run ash init

This creates ~/.ash/config.toml with a template configuration. Edit it to add your API keys:

[anthropic]
api_key = "sk-ant-..."

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

[models.default]
provider = "anthropic"
model = "claude-haiku-4-5"

[models.sonnet]
provider = "anthropic"
model = "claude-sonnet-4-5"

[embeddings]
provider = "openai"
model = "text-embedding-3-small"

See Configuration Overview for all options.

Docker Sandbox

The sandbox isolates command execution. Build the image:

uv run ash sandbox build

Check status:

uv run ash sandbox status

Database Setup

Initialize the SQLite database:

uv run ash upgrade

This runs migrations and verifies everything is ready.

Workspace

Ash uses a workspace directory for personality:

~/.ash/workspace/
├── SOUL.md    # Assistant personality
└── USER.md    # User profile (optional)

These are created automatically on first run. Edit SOUL.md to customize how Ash behaves.

Upgrading

cd ash
git pull
uv sync --all-groups
uv run ash upgrade

Troubleshooting

Docker not found

docker info

If this fails, install Docker and ensure the daemon is running.

Permission denied

Add your user to the docker group:

sudo usermod -aG docker $USER

Log out and back in.

Config issues

Check your config:

uv run ash config show

Validate it:

uv run ash config validate