---
title: "Use Autohand models in Claude Code"
source: https://docs.autohand.ai/integrations/coding-agents/claude-code
---

# Use Autohand models in Claude Code

Run Claude Code on Autohand Fantail and Moa through a local proxy that translates the Anthropic Messages API to Chat Completions.

Quick answer

## How do I use Autohand models in Claude Code?

Run a local LiteLLM proxy that turns Anthropic Messages API requests into Autohand Chat Completions requests. Then set `ANTHROPIC_BASE_URL` to the proxy, `ANTHROPIC_AUTH_TOKEN` to the proxy key, and `ANTHROPIC_MODEL` to `fantail`.

Status

Works through a local proxy

Requires

An Autohand account, an Autohand API key, Claude Code, and uv to run LiteLLM.

Configure with

Environment variables, or the `env` block in `~/.claude/settings.json`.

Subagents

`CLAUDE_CODE_SUBAGENT_MODEL="fantail"` or `model: fantail` in a subagent file.

**Know before you start:** Claude Code sends requests to the Anthropic Messages API, and the Autohand API serves Chat Completions, so Claude Code needs the proxy in this guide. Anthropic does not support routing Claude Code to non-Claude models through a gateway, so some Claude Code features might not work with Autohand models.

## 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.
-   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](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 `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.

```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: 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](https://docs.astral.sh/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`:

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

    ```bash
    # 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:

```bash
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"
```

| Variable | Purpose |
|---|---|
| ANTHROPIC_BASE_URL | Sends requests to the local proxy |
| ANTHROPIC_AUTH_TOKEN | The proxy key. The proxy holds your Autohand key. |
| ANTHROPIC_MODEL | The model for the session |
| ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL | The models behind the opus, sonnet, and haiku aliases. The haiku alias also runs background tasks. |
| CLAUDE_CODE_SUBAGENT_MODEL | The default model for subagents and agent team teammates |
| CLAUDE_CODE_MAX_CONTEXT_TOKENS | The context window for a model Claude Code does not recognize. Use 262144 for Fantail. If your main model is Moa, use 1048576. |

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.

```json
{
  "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

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

```bash
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.

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

| Symptom | Cause | Fix |
|---|---|---|
| 404 for /v1/messages | ANTHROPIC_BASE_URL points at Autohand directly. | Set ANTHROPIC_BASE_URL to http://127.0.0.1:4000 and start the proxy. |
| Requests use your Claude subscription | Only ANTHROPIC_BASE_URL is set. | Also set ANTHROPIC_AUTH_TOKEN. The credential variable replaces the saved Claude login for the session. |
| fantail is not in the model catalog | Claude Code does not know Autohand model IDs. | Set CLAUDE_CODE_MAX_CONTEXT_TOKENS. The notice does not stop the request. |
| Connection errors | The proxy is not running, or it uses a different port. | Start the proxy and match the port in ANTHROPIC_BASE_URL. |
| 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

## Claude Code and Autohand FAQ

### Why does Claude Code need a proxy for Autohand?

Claude Code sends requests to the Anthropic Messages API, and the Autohand API serves Chat Completions. The LiteLLM proxy translates between them.

### How do I run Claude Code subagents on Fantail?

Set `CLAUDE_CODE_SUBAGENT_MODEL="fantail"`, or add `model: fantail` to a subagent file.

### Does Anthropic support this setup?

No. Anthropic does not support routing Claude Code to non-Claude models through a gateway, so some features might not work.