Use Autohand models in Claude Code

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.
• Claude Code. Run claude --version to check the installed version. This guide was tested with Claude Code 2.1.283.

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 claude-code-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: Run a local LiteLLM proxy

The proxy accepts Anthropic Messages API requests on /v1/messages and forwards them to the Autohand Chat Completions API. It uses the custom_openai provider in LiteLLM, which translates each request to Chat Completions.

1. Install uv if you do not have it. The uvx command runs LiteLLM without a permanent install.
2. Save the following file as ~/.config/autohand/litellm.yaml:

   model_list:
     - model_name: fantail
       litellm_params:
         model: custom_openai/fantail
         api_base: https://api.autohand.ai/v1
         api_key: os.environ/AUTOHAND_API_KEY
         additional_drop_params: ["client_metadata"]
     - model_name: moa
       litellm_params:
         model: custom_openai/moa
         api_base: https://api.autohand.ai/v1
         api_key: os.environ/AUTOHAND_API_KEY
         additional_drop_params: ["client_metadata"]
   
   litellm_settings:
     drop_params: true
   
   general_settings:
     master_key: os.environ/LITELLM_MASTER_KEY

3. Start the proxy in a separate terminal and leave it running:

   # Choose a local key for the proxy. It must start with sk-.
   export LITELLM_MASTER_KEY="sk-autohand-local"
   
   # Start the proxy on this machine only
   uvx --from 'litellm[proxy]' litellm \
     --config ~/.config/autohand/litellm.yaml \
     --host 127.0.0.1 --port 4000

The --host 127.0.0.1 option keeps the proxy off your network, and master_key rejects requests that do not send the local key. The additional_drop_params entry removes the client_metadata field that Codex sends, which the Chat Completions client does not accept. We tested this configuration with LiteLLM 1.102.1.

Step 4: Point Claude Code at the proxy

Set these variables in the terminal where you start Claude Code:

export ANTHROPIC_BASE_URL="http://127.0.0.1:4000"
export ANTHROPIC_AUTH_TOKEN="$LITELLM_MASTER_KEY"
export ANTHROPIC_MODEL="fantail"
export ANTHROPIC_DEFAULT_OPUS_MODEL="moa"
export ANTHROPIC_DEFAULT_SONNET_MODEL="fantail"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="fantail"
export CLAUDE_CODE_SUBAGENT_MODEL="fantail"
export CLAUDE_CODE_MAX_CONTEXT_TOKENS="262144"

To keep the settings for every session, add them to the env block of ~/.claude/settings.json. Use the literal proxy key in this file, because the file does not expand shell variables.

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-autohand-local",
    "ANTHROPIC_MODEL": "fantail",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "moa",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "fantail",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "fantail",
    "CLAUDE_CODE_SUBAGENT_MODEL": "fantail",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "262144"
  }
}

Step 5: Choose Fantail or Moa

Switch models during a session with /model. Because ANTHROPIC_DEFAULT_OPUS_MODEL is moa, /model opus selects Moa and /model sonnet selects Fantail.

Step 6: Run a test prompt

Keep the proxy running and run a one-time prompt from a project folder.

claude -p "Summarize what this repository does in three sentences"

Claude Code prints a notice that fantail is not in its model catalog. The notice is expected. CLAUDE_CODE_MAX_CONTEXT_TOKENS sets the context window for the unknown model. The proxy terminal shows each POST /v1/messages request.

Subagents and Fantail

Claude Code chooses a subagent model in this order: the model in the request that starts the subagent, the model field in the subagent file, CLAUDE_CODE_SUBAGENT_MODEL, and then the model of the main session. With CLAUDE_CODE_SUBAGENT_MODEL="fantail", subagents without their own setting run on Fantail.

To set the model for one subagent, add the model field to its file in .claude/agents/ or ~/.claude/agents/. The field accepts a full model ID.

---
name: reviewer
description: Reviews a change and lists risks before it merges.
model: 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