Connect Factory Droid to Tokens

Droid is Factory's terminal coding agent. It supports bring-your-own-key custom models, declared in ~/.factory/settings.json. With Tokens, use the generic-chat-completion-api provider type, which sends OpenAI Chat Completions requests to https://tokens.bd/v1. An Anthropic Messages variant is covered below.

Install Droid#

From Factory's quickstart:

# macOS / Linux
curl -fsSL https://app.factory.ai/cli | sh

# or
brew install --cask droid
npm install -g droid

# Windows PowerShell
irm https://app.factory.ai/cli/windows | iex

Add Tokens custom models to ~/.factory/settings.json#

1. Export your key#

Create a key in the dashboard (API keys covers caps and allow-lists), then export it in your shell profile:

export TOKENS_API_KEY=tok_live_your_key

2. Add the custom model#

Add a customModels array to ~/.factory/settings.json:

{
  "customModels": [
    {
      "model": "deepseek/deepseek-v4.1-flash",
      "displayName": "DeepSeek V4.1 Flash (Tokens)",
      "baseUrl": "https://tokens.bd/v1",
      "apiKey": "${TOKENS_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "noImageSupport": true
    }
  ]
}

Field by field:

• model is the exact Tokens ID, sent upstream unchanged. The slash in the ID is fine.
• displayName is what you see in Droid's model menu.
• baseUrl is the OpenAI-compatible base, with /v1.
• apiKey uses ${VAR} expansion, so the key stays in your environment instead of the file.
• provider sets the protocol. See the table below.
• maxOutputTokens is an example; use the model's output limit from the model catalog.
• noImageSupport: true stops Droid from sending images to a text-only model. Remove it for models the catalog lists with image input.

If the file already has other settings, add customModels alongside them rather than replacing the file.

Pick the provider type#

The provider value must be exactly one of these:

Use generic-chat-completion-api for Tokens. The openai type looks like the obvious choice but it means the Responses API. Tokens serves /v1/responses, but whether it works depends on the upstream provider behind each model.

Anthropic Messages variant#

For the Messages API, set "provider": "anthropic" and "baseUrl": "https://tokens.bd", without /v1, matching Factory's own https://api.anthropic.com example. Droid sends the key in x-api-key by default, which Tokens accepts. "authMode": "bearer" switches it to Authorization: Bearer if you prefer. The format is described in Messages.

Legacy config.json#

Older setups use ~/.factory/config.json with snake_case custom_models. Droid still loads it, but that file does not expand ${VAR}, so the key would have to be written in plain text. Move to settings.json.

Switch models#

Add one object to customModels per Tokens model. In Droid, run /model; custom models appear in their own "Custom models" section. Droid watches the settings file, so new entries show up without a restart.

Get exact IDs from the catalog or:

curl -s https://tokens.bd/v1/models -H "Authorization: Bearer $TOKENS_API_KEY"

Choosing a model covers which models suit agent work.

Verify it works#

Check the key and model directly:

curl -s https://tokens.bd/v1/chat/completions \
  -H "Authorization: Bearer $TOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4.1-flash", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'

Then run droid, choose "DeepSeek V4.1 Flash (Tokens)" from /model, and ask it to read a file in the current project. The request appears in your dashboard usage analytics.

Troubleshooting#

The model doesn't appear under Custom models. The JSON is invalid (a trailing comma is the usual cause), or customModels was put in config.json with the camelCase name.

401 missing_api_key. ${TOKENS_API_KEY} expanded to nothing. Export the variable in the shell you start droid from.

401 invalid_api_key. Wrong, revoked or rotated key. Rotation stops the old secret immediately.

404 model_not_found. model must be the full Tokens ID with its provider prefix.

404 on every request. Check baseUrl: https://tokens.bd/v1 for generic-chat-completion-api, https://tokens.bd for anthropic.

Odd behavior with tools or caching. Factory says only official Anthropic and OpenAI models are fully tested with Droid, and prompt caching on generic providers isn't guaranteed. Try a different model before assuming the gateway is at fault.

429 errors. See Retry-After, and Troubleshooting for each rate limit code.

The request format is in Chat Completions. Other terminal agents with similar setups: Claude Code, OpenCode and Crush.

Sources: Factory docs, BYOK overview, Droid quickstart, checked October 2026.