Configuration

ayo uses two directories: one for configuration and one for data. Configuration is human-editable; data is managed by ayo.

Directory Structure

                ~/.config/ayo/                    # Configuration (user-editable)
├── ayo.json                      # Main config
├── agents/                       # User-defined agents
│   └── @myagent/
│       ├── config.json
│       └── system.md
├── skills/                       # User-defined skills
├── flows/                        # User-defined flows
└── prompts/                      # Custom prefix/suffix prompts

~/.local/share/ayo/               # Data (managed by ayo)
├── ayo.db                        # SQLite database
├── agents/                       # Built-in agents
├── skills/                       # Built-in skills
├── plugins/                      # Installed plugins
├── sessions/                     # Session data
│   └── {session-id}/.tickets/    # Per-session tickets
└── sandboxes/
    ├── squads/                   # Squad sandboxes
    └── pool/                     # Pre-warmed containers
            

Main Config (ayo.json)

Location: ~/.config/ayo/ayo.json

                {
  "default_model": "claude-sonnet-4-20250514",
  "provider": {
    "name": "anthropic"
  },
  "delegates": {
    "research": "@researcher",
    "writing": "@writer"
  }
}
            

Fields

Field	Type	Description
`default_model`	string	Model to use when not specified
`provider.name`	string	API provider: anthropic, openai, openrouter
`delegates`	object	Default agents for delegation by topic

Environment Variables

API Keys

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic API key (recommended)
`OPENAI_API_KEY`	OpenAI API key
`OPENROUTER_API_KEY`	OpenRouter API key

Directories

Variable	Default	Description
`AYO_CONFIG`	`~/.config/ayo`	Config directory
`AYO_HOME`	`~/.local/share/ayo`	Data directory

Provider Configuration

Anthropic

export ANTHROPIC_API_KEY="sk-ant-..."

                // ayo.json
{
  "provider": {
    "name": "anthropic"
  },
  "default_model": "claude-sonnet-4-20250514"
}
            

OpenAI

export OPENAI_API_KEY="sk-..."

                // ayo.json
{
  "provider": {
    "name": "openai"
  },
  "default_model": "gpt-4o"
}
            

OpenRouter

export OPENROUTER_API_KEY="sk-or-..."

                // ayo.json
{
  "provider": {
    "name": "openrouter"
  },
  "default_model": "anthropic/claude-3.5-sonnet"
}
            

Model Names

Anthropic Models

claude-sonnet-4-20250514 — Claude Sonnet 4 (recommended)
claude-opus-4-20250514 — Claude Opus 4
claude-3-5-sonnet-20241022 — Claude 3.5 Sonnet

OpenAI Models

gpt-4o — GPT-4o
gpt-4-turbo — GPT-4 Turbo
gpt-3.5-turbo — GPT-3.5 Turbo

Precedence

Configuration is loaded in this order (later overrides earlier):

Built-in defaults
~/.config/ayo/ayo.json
Environment variables
Command-line flags