Use Autohand models in Codex

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.
• Codex CLI. Run codex --version to check the installed version. This guide was tested with Codex CLI 0.154.0.

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 codex-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 Responses API requests on /v1/responses 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: Add Autohand as a Codex model provider

Open ~/.codex/config.toml and add the provider. If the file already sets model or model_provider, replace those lines.

model = "fantail"
model_provider = "autohand"

[model_providers.autohand]
name = "Autohand"
base_url = "http://127.0.0.1:4000/v1"
env_key = "LITELLM_MASTER_KEY"
wire_api = "responses"

Step 5: Choose Fantail or Moa

The model setting chooses the default. Use the -m option to pick a model for one session.

# Plan a larger change with Moa
codex -m moa "Map the payment flow and propose a refactor plan"

Step 6: Run a test prompt

Keep the proxy running, open a new terminal in a project folder, and run a one-time prompt.

codex exec "Summarize what this repository does in three sentences"

A reply means the full path works: Codex, the proxy, and the Autohand API. The proxy terminal shows each POST /v1/responses request.

Subagents and Fantail

Codex can start subagents for parallel work. Set a default model for them in the [agents] section of ~/.codex/config.toml. Subagents use the same Autohand provider as the main session.

[agents]
default_subagent_model = "fantail"

To give one custom agent its own model, create a file in ~/.codex/agents/ or in the project folder .codex/agents/.

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews a change and lists risks before it merges."
model = "fantail"
sandbox_mode = "read-only"
developer_instructions = "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