Use Autohand models in OpenCode

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.
• OpenCode. Run opencode --version to check the installed version. This guide was tested with OpenCode 1.17.3.

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 opencode-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 an OpenCode provider

Open ~/.config/opencode/opencode.json for every project, or opencode.json in a project root for one project. Add the provider:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "autohand": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Autohand",
      "options": {
        "baseURL": "https://api.autohand.ai/v1",
        "apiKey": "{env:AUTOHAND_API_KEY}"
      },
      "models": {
        "fantail": {
          "name": "Autohand Fantail",
          "limit": { "context": 262144, "output": 16000 }
        },
        "moa": {
          "name": "Autohand Moa",
          "limit": { "context": 1048576, "output": 262144 }
        }
      }
    }
  },
  "model": "autohand/fantail",
  "small_model": "autohand/fantail"
}

Confirm that OpenCode lists both models:

opencode models autohand

Step 4: Choose Fantail or Moa

Switch models during a session with /models, or pass --model autohand/moa when you start OpenCode.

Step 5: Run a test prompt

opencode run "Summarize what this repository does in three sentences"

OpenCode prints the agent and model, for example build · fantail, followed by the reply.

Subagents and Fantail

OpenCode has two primary agents, build and plan, and three built-in subagents: general, explore, and scout. Without a model setting, a subagent uses the model of the primary agent that started it. Set models per agent in opencode.json:

{
  "agent": {
    "plan": { "model": "autohand/moa" },
    "general": { "model": "autohand/fantail" },
    "explore": { "model": "autohand/fantail" },
    "scout": { "model": "autohand/fantail" }
  }
}

For a custom subagent, create a Markdown file in ~/.config/opencode/agents/ or .opencode/agents/. The file name becomes the agent name.

---
description: Reviews a change and lists risks before it merges
mode: subagent
model: autohand/fantail
---

Read the diff, list concrete risks, and cite each file and line.

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