docs/getting-started/setup.md

# Setup

Configure your LLM provider and model selection for ACE.

## Guided Setup (Recommended)

The `ace setup` command walks you through configuration interactively — it validates the connection first, and only asks for credentials if needed.

```bash

ace setup

```

```

ACE Setup



Step 1: Choose your model



  Examples: gpt-4o-mini, claude-sonnet-4-20250514, ollama/llama2

  Search models: ace models <query>



  Default model: gpt-4o-mini

  v Connected! (gpt-4o-mini via openai, 203ms)

    Using OPENAI_API_KEY



Step 2: Role assignment



  ACE uses three roles. You can assign a different model to each,

  or use the same model for all (recommended to start).



  Use this model for all roles? [Y/n]: n



  Agent (executes tasks) [gpt-4o-mini]: claude-sonnet-4-20250514

  ! No credentials found for anthropic

  ANTHROPIC_API_KEY: sk-ant-...

  v Connected! (claude-sonnet-4-20250514 via anthropic, 347ms)

  v Saved credentials to .env



  Reflector (analyses results) [gpt-4o-mini]:

  Skill Manager (updates skillbook) [gpt-4o-mini]:



v Saved model config to ace.toml



  Configuration summary:

    default:        gpt-4o-mini

    agent:          claude-sonnet-4-20250514

```

The wizard tries the connection immediately — if your credentials are already in the environment (via `.env`, exported variables, or cloud auth like AWS), it just works. It only prompts for keys when the connection actually fails.

This creates two files:

| File | Contains | Commit to git? |
|------|----------|----------------|
| `.env` | API keys only | No (gitignore it) |
| `ace.toml` | Model names per role | Yes (no secrets) |

Then in your code:

```python

from ace import ACELiteLLM



ace = ACELiteLLM.from_setup()

answer = ace.ask("What is 2+2?")

```

## Manual Setup

If you prefer not to use the CLI, set environment variables directly.

### 1. Set API keys

=== "Shell"

    ```bash

    export OPENAI_API_KEY="sk-..."

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

    ```


=== ".env file"

    ```bash

    # .env (add to .gitignore)

    OPENAI_API_KEY=sk-...

    ANTHROPIC_API_KEY=sk-ant-...

    ```


### 2. Use in code

```python

from ace import ACELiteLLM



# Single model for all roles

ace = ACELiteLLM.from_model("gpt-4o-mini")

```

```python

from ace import ACELiteLLM, ACEModelConfig, ModelConfig



# Different models per role

ace = ACELiteLLM.from_config(ACEModelConfig(

    default=ModelConfig(model="gpt-4o-mini"),

    agent=ModelConfig(model="claude-sonnet-4-20250514"),

))

```

## Per-Role Model Selection

ACE has three roles, each making LLM calls. You can assign different models to optimise cost vs quality:

| Role | What it does | Recommendation |
|------|-------------|----------------|
| **Agent** | Executes tasks, produces answers | Strong reasoning model |
| **Reflector** | Analyses results, extracts lessons | Good analysis, lower cost OK |
| **Skill Manager** | Updates the skillbook | Structured output reliability |

Example `ace.toml`:

```toml

[default]

model = "gpt-4o-mini"



[agent]

model = "claude-sonnet-4-20250514"

max_tokens = 4096



[reflector]

model = "gpt-4o-mini"

```

Roles without an explicit section use `[default]`.

## Discovering Models

### Search available models

Use multiple terms to narrow results — all terms must match:

```bash

ace models claude             # All Claude models

ace models haiku us           # Only US-region Haiku models

ace models gpt 4o             # GPT-4o variants

ace models --provider openai  # All OpenAI models

```

Output shows model name, provider, pricing, and whether your API key is configured:

```

Model                                         Provider        Input $/M  Output $/M  Key

------------------------------------------------------------------------------------------

us.anthropic.claude-haiku-4-5-20251001-v1:0   bedrock_converse $1.10      $5.50       v

claude-haiku-4-5-20251001                     anthropic        $1.00      $5.00       x



Showing 20 of 40 models. Narrow your search: ace models <query> or use --limit 40

```

### Validate a specific model

```bash

ace validate us.anthropic.claude-haiku-4-5-20251001-v1:0

```

Makes a tiny test call (3 tokens) to confirm the key, model, and network all work.

## Supported Providers

ACE uses [LiteLLM](https://docs.litellm.ai/) for model access. Any model string LiteLLM supports will work:

| Provider | Model Example | Env Variable |
|----------|--------------|--------------|
| OpenAI | `gpt-4o-mini` | `OPENAI_API_KEY` |
| Anthropic | `claude-sonnet-4-20250514` | `ANTHROPIC_API_KEY` |
| AWS Bedrock | `us.anthropic.claude-haiku-4-5-20251001-v1:0` | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION_NAME` |
| Google Gemini | `gemini/gemini-2.0-flash` | `GEMINI_API_KEY` |
| DeepSeek | `deepseek/deepseek-chat` | `DEEPSEEK_API_KEY` |
| Groq | `groq/llama-3.1-70b` | `GROQ_API_KEY` |
| Ollama (local) | `ollama/llama2` | --- |
| Azure OpenAI | `azure/gpt-4` | `AZURE_API_KEY` |
| OpenRouter | `openrouter/anthropic/claude-3.5-sonnet` | `OPENROUTER_API_KEY` |

100+ providers supported. Run `ace models` to search the full catalog.

## Troubleshooting

### "No ace.toml found"

Run `ace setup` or use `ACELiteLLM.from_model("gpt-4o-mini")` instead of `from_setup()`.

### "Invalid API key"

```bash

# Re-validate

ace validate gpt-4o-mini



# Re-run setup to fix

ace setup

```

### "Model not found"

The model string may have a typo. `ace validate` and `ace setup` suggest alternatives:

```bash

ace validate claud-sonnet

# x Model 'claud-sonnet' not found at the provider.

# Did you mean:

#   - claude-sonnet-4-20250514

#   - claude-3-5-sonnet-20241022

```

### "Could not detect a provider"

Use the `provider/model-name` format:

```bash

# Instead of just "llama2":

ollama/llama2

groq/llama-3.1-70b

```

Search for the correct model string: `ace models llama`

## What to Read Next

- [Quick Start](quick-start.md) --- build your first self-learning agent
- [How ACE Works](../concepts/overview.md) --- understand the three-role architecture
- [Integrations](../integrations/index.md) --- LangChain, Browser-Use, Claude Code