Use Autohand models in Factory Droid

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 Droid CLI from Factory. Check the version with droid --version.

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 droid-laptop.
4. Select Create Key and copy the value. Console shows the key only once.

Step 2: Store the key in an environment variable

Store the key in an environment variable so it stays out of configuration files and source control.

# macOS and Linux (add the line to ~/.zshrc or ~/.bashrc to keep it)
export AUTOHAND_API_KEY="your-api-key"

# Windows PowerShell (current session)
$env:AUTOHAND_API_KEY = "your-api-key"

# Windows (persist for new sessions)
setx AUTOHAND_API_KEY "your-api-key"

Confirm that the key works and that your plan can see the models:

curl https://api.autohand.ai/v1/models \
  -H "Authorization: Bearer $AUTOHAND_API_KEY"

The response lists fantail, and moa when your plan includes it. A 401 response means the key is missing or not recognised.

Step 3: Add Autohand to customModels

Open ~/.factory/settings.json and add the Autohand models to the customModels array. Keep any settings that are already in the file.

{
  "customModels": [
    {
      "model": "fantail",
      "displayName": "Autohand Fantail",
      "baseUrl": "https://api.autohand.ai/v1",
      "apiKey": "${AUTOHAND_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 16000
    },
    {
      "model": "moa",
      "displayName": "Autohand Moa",
      "baseUrl": "https://api.autohand.ai/v1",
      "apiKey": "${AUTOHAND_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 262144
    }
  ]
}

• provider must be generic-chat-completion-api, which uses the OpenAI Chat Completions format.
• apiKey uses ${AUTOHAND_API_KEY}, which Droid expands from the environment when it reads the file.
• model is the ID that Droid sends to Autohand.

To try the configuration without changing your saved settings, put it in a separate file and pass it with --settings <path>. Droid merges that file for the current process only.

Step 4: Choose Fantail or Moa

In an interactive session, run /model and select Autohand Fantail or Autohand Moa in the Custom models section. For scripts, pass the model with -m and the custom: prefix followed by the model value from your settings.

Step 5: Run a test prompt

droid exec -m custom:fantail "Summarize what this repository does in three sentences."

A text answer confirms that Droid reaches Autohand. Add -o stream-json to see error events when a run fails.

Run custom droids on Fantail

Custom droids are Droid's subagents. Each one is a Markdown file with YAML frontmatter in .factory/droids/ for a project or ~/.factory/droids/ for all projects. Set model to custom:fantail to run the droid on Fantail. The default, inherit, uses the parent session's model.

---
name: fast-explorer
description: Maps files, call sites, and tests for a question without editing anything
model: custom:fantail
tools: ["Read", "LS", "Grep", "Glob"]
---

Answer the question you are given by reading the repository.
Return the relevant file paths and a short explanation.

Droid starts custom droids through its Task tool. Custom droids are enabled by default; you can turn them off in /settings under Experimental.

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