Configuration Overview

Ash configuration is loaded from a single TOML file.

Config File Location

Default location:

~/.ash/config.toml

If ASH_HOME is set, config path becomes:

$ASH_HOME/config.toml

Create a starter config:

uv run ash init

Bootstrap Workflow

uv run ash init
uv run ash config show
uv run ash config validate
uv run ash auth login
uv run ash upgrade

Core Example (OAuth-first)

workspace = "~/.ash/workspace"
timezone = "America/Los_Angeles"

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

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

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

[sandbox]
workspace_access = "rw"
sessions_access = "ro"
chats_access = "ro"

[memory]
max_context_messages = 20
context_token_budget = 100000

[image]
enabled = true
provider = "openai"

[browser]
enabled = true
provider = "sandbox"

[sessions]
mode = "persistent"
max_concurrent = 2

API Key Example (alternative)

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

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

Environment Variables

Variable	Purpose
`ASH_HOME`	Base directory for Ash state (`config.toml`, logs, sessions, auth)
`OPENAI_API_KEY`	OpenAI API key (for `provider = "openai"`)
`ANTHROPIC_API_KEY`	Anthropic API key
`TELEGRAM_BOT_TOKEN`	Telegram bot token
`BRAVE_SEARCH_API_KEY`	Brave Search API key
`KERNEL_API_KEY`	Kernel API key (when `[browser].provider = "kernel"`)
`SENTRY_DSN`	Sentry DSN

Configuration Sections

Section	Purpose
`workspace`, `timezone`	Global behavior
`[models.*]`	Named model aliases (must include `default`)
`[openai]`, `[anthropic]`	Provider API key config
`[telegram]`	Telegram provider settings
`[sandbox]`	Sandbox runtime and mount settings
`[memory]`	Memory retention and extraction tuning
`[image]`	Vision/image understanding preprocessing
`[browser]`	Browser sessions and page actions
`[conversation]`	Conversation context behavior
`[sessions]`	Session runtime settings
`[embeddings]`	Embedding provider/model
`[agents.*]`	Per-agent overrides
`[skills]` / `[[skills.sources]]` / `[skills.<name>]`	Skill source and per-skill settings
`[env]`	Environment variables injected into runtime
`[brave_search]`, `[sentry]`, `[server]`	Optional subsystem config