---
title: "Use Autohand models in Factory Droid"
source: https://docs.autohand.ai/integrations/coding-agents/factory-droid
---

# Use Autohand models in Factory Droid

Register Autohand as a custom model in Droid, select it with /model or droid exec, and assign Fantail to custom droids.

Quick answer

## How do I use Autohand models in Factory Droid?

Add Fantail and Moa to the `customModels` array in `~/.factory/settings.json` with the `generic-chat-completion-api` provider and the base URL `https://api.autohand.ai/v1`. Droid reads the key from `AUTOHAND_API_KEY`. Select the model with `/model`, or pass `-m custom:fantail` to `droid exec`.

Status

Available as a bring-your-own-key custom model

Requires

An Autohand account, an Autohand API key, and the Droid CLI.

Configure with

The `customModels` array in `~/.factory/settings.json`.

Best for

Running scripted `droid exec` jobs and custom droids on Fantail.

**Know before you start:** Use the `generic-chat-completion-api` provider. The `openai` and `anthropic` provider values use API formats that Autohand does not serve.

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

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

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

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

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

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

| Model ID | Use it for | Context | Max output | Plans |
|---|---|---|---|---|
| fantail | Main coding loops, quick fixes, reviews, and sub-agents | 262,144 tokens | 16,000 tokens | Free and above |
| moa | Planning, large refactors, and multi-file reasoning | 1,048,576 tokens | 262,144 tokens | Pro and above |

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

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

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

| Symptom | Cause | Resolution |
|---|---|---|
| 401 with Credential not recognised. or Missing Autohand credential. | The agent sent no key, a mistyped key, or a revoked key. | Confirm that AUTOHAND_API_KEY is set in the environment that starts the agent. Create a new key in Console if needed. |
| 404 or Not found | The base URL or the API format is wrong. | Use https://api.autohand.ai/v1 with the OpenAI Chat Completions format. Autohand does not serve /v1/responses or /v1/messages. |
| Model not found or not available | The model ID is misspelled, or your plan does not include it. | Use the exact IDs fantail or moa. Moa requires the Pro plan or above. |
| Context length or output errors | The agent uses default limits for an unknown model. | Set the limits for Fantail (262,144 context, 16,000 output) or Moa (1,048,576 context, 262,144 output). |
| Exec failed with no detail | Plain text output hides the underlying error. | Run the command again with -o stream-json and read the error event. |

## 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

## Factory Droid and Autohand FAQ

### Which provider value do I use for Autohand in Droid?

Use `generic-chat-completion-api` with the base URL `https://api.autohand.ai/v1`.

### How do I select an Autohand model in droid exec?

Pass `-m custom:fantail` or `-m custom:moa`, where the part after `custom:` is the `model` value from `customModels`.

### How do I run a custom droid on Fantail?

Set `model: custom:fantail` in the frontmatter of the droid file.