Use Autohand models in Pi

Prerequisites

• An Autohand account. Sign up or sign in to Console. 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.
2. Open 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.

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

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

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.

{
  "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:

pi --list-models autohand

Step 4: Choose Fantail or Moa

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

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/.

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

Next steps

• Use Autohand models in other coding agents
• Compare Autohand models
• Fantail model reference
• Moa model reference
• Create and protect an API key