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

# Use Autohand models in Pi

Add Autohand as a custom provider in Pi and choose Fantail or Moa with the model selector.

Quick answer

## How do I use Autohand models in Pi?

Add an `autohand` provider to `~/.pi/agent/models.json` with `"api": "openai-completions"`, the base URL `https://api.autohand.ai/v1`, and `"apiKey": "$AUTOHAND_API_KEY"`. Then start Pi with `--model autohand/fantail`.

Status

Available through a custom provider

Requires

An Autohand account, an Autohand API key, and the Pi coding agent.

Configure with

`~/.pi/agent/models.json`

Subagents

Through the subagent example extension, with `model: autohand/fantail`

**Know before you start:** Pi does not include subagents. You can add them with an extension, as described later in this guide.

## 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.
-   The Pi coding agent. Run `pi --version` to check the installed version. This guide was tested with Pi 0.84.4.

## 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 `pi-laptop`.
4.  Select **Create Key** and copy the value. Console shows the key only once.

## Step 2: Store the key

Store the key in the `AUTOHAND_API_KEY` environment variable. Add the line to your shell profile so new terminals keep it. Do not commit the key to a repository.

```bash
# macOS or Linux: add to ~/.zshrc or ~/.bashrc
export AUTOHAND_API_KEY="your-autohand-api-key"
```

```powershell
# Windows PowerShell: saves the variable for new sessions
[Environment]::SetEnvironmentVariable("AUTOHAND_API_KEY", "your-autohand-api-key", "User")
```

Confirm that the key works before you configure the agent. The request lists the models your plan can use.

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

## Step 3: Add Autohand as a Pi provider

Create or open `~/.pi/agent/models.json` and add the provider. If the file already has a `providers` object, add the `autohand` entry to it.

```json
{
  "providers": {
    "autohand": {
      "baseUrl": "https://api.autohand.ai/v1",
      "api": "openai-completions",
      "apiKey": "$AUTOHAND_API_KEY",
      "models": [
        {
          "id": "fantail",
          "name": "Autohand Fantail",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 262144,
          "maxTokens": 16000
        },
        {
          "id": "moa",
          "name": "Autohand Moa",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 1048576,
          "maxTokens": 262144
        }
      ]
    }
  }
}
```

The value `$AUTOHAND_API_KEY` tells Pi to read the key from the environment variable. A value without the `$` prefix is used as the literal key. Pi reloads the file each time you open `/model`, so you do not need to restart it.

Confirm that Pi lists both models:

```bash
pi --list-models autohand
```

## Step 4: Choose Fantail or Moa

| Model ID | Use it for | Context | Max output | Plans |
|---|---|---|---|---|
| fantail | Fast agent loops, quick fixes, reviews, and subagents | 256K tokens | 16K tokens | Free and above |
| moa | Planning, large refactors, and repository-wide changes | 1M tokens | 262,144 tokens | Pro and above |

Select a model with `--model autohand/fantail` or `--model autohand/moa`, or with `/model` during a session. Moa accepts the `medium`, `high`, and `xhigh` reasoning levels.

## Step 5: Run a test prompt

```bash
pi --model autohand/fantail -p "Summarize what this repository does in three sentences"
```

The `-p` option runs one prompt and exits. A reply means Pi reached the Autohand API with your key.

## Subagents and Fantail

Pi does not include subagents. The Pi package ships a subagent example extension in `examples/extensions/subagent/`. Each subagent runs as a separate `pi` process and can set its own model. Follow the installation steps in the extension README, then add `model` to each agent file in `~/.pi/agent/agents/`.

```markdown
---
name: scout
description: Fast reconnaissance that returns compressed context
tools: read, grep, find, ls
model: autohand/fantail
---

Find the files that matter for the task and summarize them briefly.
```

When an agent file has no `model` field, the subagent uses the model of the session that started it.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Autohand models are missing from /model | Pi cannot resolve the key, so it marks the models as unavailable. | Set AUTOHAND_API_KEY and keep the $ prefix in apiKey. |
| Errors about the developer role or reasoning_effort | Pi sends these fields for reasoning models. | Add "compat": { "supportsDeveloperRole": false } to the Moa entry. |
| 401 with Credential not recognised | The key is wrong, revoked, or not set in the environment the agent reads. | Create a new key in Console, set AUTOHAND_API_KEY again, and open a new terminal. |
| 401 with Missing Autohand credential | The request reached Autohand without an Authorization header. | Check that the agent reads the variable name shown in this guide. |
| Model not found | The model ID is misspelled, or your plan does not include it. | Use fantail or moa in lowercase. Moa requires the Pro plan or above. |
| Context or output limit errors | The agent uses default limits for a model it does not recognize. | Set the limits for Fantail (262,144 context, 16,000 output) or Moa (1,048,576 context, 262,144 output). |

## 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

## Pi and Autohand FAQ

### Which API type does Pi use for Autohand?

Use `"api": "openai-completions"`, which is the OpenAI Chat Completions format.

### How does Pi read my Autohand key?

Set `"apiKey": "$AUTOHAND_API_KEY"` in `models.json`. The `$` prefix reads the environment variable.

### Does Pi have subagents?

Not by default. The subagent example extension adds them, and each agent file can set `model: autohand/fantail`.