--- title: "Use Autohand models in OpenCode" source: https://docs.autohand.ai/integrations/coding-agents/opencode --- # Use Autohand models in OpenCode Add Autohand as an OpenCode provider, plan with Moa, and run subagents on Fantail. Quick answer ## How do I use Autohand models in OpenCode? Add an `autohand` provider to `opencode.json` that uses the `@ai-sdk/openai-compatible` package, the base URL `https://api.autohand.ai/v1`, and `"apiKey": "{env:AUTOHAND_API_KEY}"`. Then set `"model": "autohand/fantail"`. Status Available through a custom provider Requires An Autohand account, an Autohand API key, and OpenCode. Configure with `~/.config/opencode/opencode.json` or a project `opencode.json` Subagents `agent..model`, or `model` in an agent file **Know before you start:** OpenCode installs the `@ai-sdk/openai-compatible` package the first time it loads the provider, so the first run needs network access. ## 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. - 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](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 `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. ```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 an OpenCode provider Open `~/.config/opencode/opencode.json` for every project, or `opencode.json` in a project root for one project. Add the provider: ```json { "$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" } ``` | Key | Purpose | |---|---| | npm | The AI SDK package for OpenAI-compatible APIs | | options.apiKey | Reads the key from AUTOHAND_API_KEY | | limit | The context and output limits for each model | | model | The default model, in provider/model form | | small_model | The model for light tasks, such as session titles | Confirm that OpenCode lists both models: ```bash opencode 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 | Switch models during a session with `/models`, or pass `--model autohand/moa` when you start OpenCode. ## Step 5: Run a test prompt ```bash 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`: ```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. ```markdown --- 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 | Symptom | Cause | Fix | |---|---|---| | Autohand models do not appear | OpenCode did not load the file, or the JSON is not valid. | Run opencode models autohand and fix any errors it reports. | | The first run fails to install the provider | OpenCode cannot reach the npm registry. | Run OpenCode once with network access. | | 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 ## OpenCode and Autohand FAQ ### Which package does OpenCode use for Autohand? Use `@ai-sdk/openai-compatible` with `baseURL` set to `https://api.autohand.ai/v1`. ### How do I run OpenCode subagents on Fantail? Set `"model": "autohand/fantail"` for `general`, `explore`, and `scout` in the `agent` section. ### Can I use Autohand in one project only? Yes. Put the provider in `opencode.json` in the project root.