---
title: "Use Autohand models in Aider"
source: https://docs.autohand.ai/integrations/coding-agents/aider
---

# Use Autohand models in Aider

Send Aider requests to Autohand with the openai/ model prefix, and let Fantail handle the weak-model and editor roles.

Quick answer

## How do I use Autohand models in Aider?

Aider reaches OpenAI-compatible APIs through the `openai/` model prefix. Set the API base to `https://api.autohand.ai/v1`, pass your Autohand key as the OpenAI API key, and start Aider with `--model openai/fantail` or `--model openai/moa`.

Status

Available through the OpenAI-compatible model prefix

Requires

An Autohand account, an Autohand API key, and Aider.

Configure with

`--openai-api-base` and `--openai-api-key`, or the matching `OPENAI_API_BASE` and `OPENAI_API_KEY` variables and `.aider.conf.yml`.

Best for

Architect mode with Moa planning and Fantail editing.

**Know before you start:** Aider has no subagents. Its weak model and editor model are the closest equivalent, and both can use Fantail.

## Prerequisites

-   An Autohand account. [Sign up or sign in to Console](https://console.autohand.ai/). The Free plan includes Fantail. Moa requires the Pro plan or above.
-   An Autohand API key. The first step shows how to create one.
-   Aider. Install it with `python -m pip install aider-install` and then run `aider-install`.

## Step 1: Create an Autohand API key

1.  Sign in to [Autohand Console](https://console.autohand.ai/).
2.  Open [API Keys](https://console.autohand.ai/api-keys) and select **Create API Key**.
3.  Enter a name that identifies the agent and machine, for example `aider-laptop`.
4.  Select **Create Key** and copy the value. Console shows the key only once.

## Step 2: Store the key in an environment variable

Store the key in an environment variable so it stays out of configuration files and source control.

```bash
# macOS and Linux (add the line to ~/.zshrc or ~/.bashrc to keep it)
export AUTOHAND_API_KEY="your-api-key"
```

```powershell
# Windows PowerShell (current session)
$env:AUTOHAND_API_KEY = "your-api-key"

# Windows (persist for new sessions)
setx AUTOHAND_API_KEY "your-api-key"
```

Confirm that the key works and that your plan can see the models:

```bash
curl https://api.autohand.ai/v1/models \
  -H "Authorization: Bearer $AUTOHAND_API_KEY"
```

The response lists `fantail`, and `moa` when your plan includes it. A `401` response means the key is missing or not recognised.

## Step 3: Point Aider at Autohand

Aider reads the OpenAI-compatible endpoint from `OPENAI_API_BASE` and the key from `OPENAI_API_KEY`. Set both from your Autohand values:

```bash
export OPENAI_API_BASE="https://api.autohand.ai/v1"
export OPENAI_API_KEY="$AUTOHAND_API_KEY"
```

```powershell
$env:OPENAI_API_BASE = "https://api.autohand.ai/v1"
$env:OPENAI_API_KEY = $env:AUTOHAND_API_KEY
```

If you also use OpenAI directly, pass the values as options instead, so the variables stay free for OpenAI:

```bash
aider --model openai/fantail \
  --openai-api-base https://api.autohand.ai/v1 \
  --openai-api-key "$AUTOHAND_API_KEY"
```

To keep the settings with a repository, add a `.aider.conf.yml` file to the repository root. Keep the key out of this file.

```yaml
# .aider.conf.yml
model: openai/moa
weak-model: openai/fantail
editor-model: openai/fantail
openai-api-base: https://api.autohand.ai/v1
```

## Step 4: Choose Fantail or Moa and set the limits

| Model ID | Use it for | Context | Max output | Plans |
|---|---|---|---|---|
| fantail | Main coding loops, quick fixes, reviews, and sub-agents | 262,144 tokens | 16,000 tokens | Free and above |
| moa | Planning, large refactors, and multi-file reasoning | 1,048,576 tokens | 262,144 tokens | Pro and above |

Aider does not know the Autohand models by default, so it warns about unknown context limits. Add a `.aider.model.metadata.json` file to your home directory or repository root to set the limits:

```json
{
  "openai/fantail": {
    "max_input_tokens": 262144,
    "max_output_tokens": 16000,
    "input_cost_per_token": 0,
    "output_cost_per_token": 0,
    "litellm_provider": "openai",
    "mode": "chat"
  },
  "openai/moa": {
    "max_input_tokens": 1048576,
    "max_output_tokens": 262144,
    "input_cost_per_token": 0,
    "output_cost_per_token": 0,
    "litellm_provider": "openai",
    "mode": "chat"
  }
}
```

Aider has no Autohand prices, so the costs are set to `0`. Check usage in Console. You can also pass the file with `--model-metadata-file`.

## Step 5: Run a test prompt

```bash
aider --model openai/fantail --message "Summarize what this repository does in three sentences."
```

A text answer confirms that Aider reaches Autohand. An `AuthenticationError` that mentions `Credential not recognised` means the key is wrong.

## Use Fantail for the weak and editor models

Aider has no subagents. It uses two helper roles that you can assign to Fantail:

-   The **weak model** writes commit messages and summarizes chat history. Set it with `--weak-model openai/fantail`.
-   The **editor model** turns the main model's plan into file edits in architect mode. Set it with `--editor-model openai/fantail`.

To plan with Moa and edit with Fantail, start Aider in architect mode:

```bash
aider --architect --model openai/moa --editor-model openai/fantail --weak-model openai/fantail
```

To make these roles the default for each model, add a `.aider.model.settings.yml` file:

```yaml
- name: openai/moa
  edit_format: diff
  weak_model_name: openai/fantail
  editor_model_name: openai/fantail
  editor_edit_format: editor-diff
  use_repo_map: true

- name: openai/fantail
  edit_format: diff
  weak_model_name: openai/fantail
  use_repo_map: true
```

## Troubleshooting

| Symptom | Cause | Resolution |
|---|---|---|
| 401 with Credential not recognised. or Missing Autohand credential. | The agent sent no key, a mistyped key, or a revoked key. | Confirm that AUTOHAND_API_KEY is set in the environment that starts the agent. Create a new key in Console if needed. |
| 404 or Not found | The base URL or the API format is wrong. | Use https://api.autohand.ai/v1 with the OpenAI Chat Completions format. Autohand does not serve /v1/responses or /v1/messages. |
| Model not found or not available | The model ID is misspelled, or your plan does not include it. | Use the exact IDs fantail or moa. Moa requires the Pro plan or above. |
| Context length or output errors | The agent uses default limits for an unknown model. | Set the limits for Fantail (262,144 context, 16,000 output) or Moa (1,048,576 context, 262,144 output). |
| Warning about an unknown model or context window | Aider has no metadata for the Autohand model. | Add .aider.model.metadata.json from Step 4. |

## Next steps

-   [Use Autohand models in other coding agents](https://docs.autohand.ai/integrations/coding-agents/)
-   [Compare Autohand models](https://docs.autohand.ai/models/)
-   [Fantail model reference](https://docs.autohand.ai/models/fantail/)
-   [Moa model reference](https://docs.autohand.ai/models/moa/)
-   [Create and protect an API key](https://docs.autohand.ai/agent-sdk/api-key-setup)

Common questions

## Aider and Autohand FAQ

### What model name do I use for Autohand in Aider?

Use `openai/fantail` or `openai/moa`. The `openai/` prefix tells Aider to use the OpenAI-compatible API.

### Does Aider support subagents?

No. Aider uses a weak model and an editor model instead, and both can use `openai/fantail`.

### Where do I set the Autohand base URL in Aider?

Set `OPENAI_API_BASE`, pass `--openai-api-base`, or add `openai-api-base` to `.aider.conf.yml`.