RealRelay.ai
Coding agents

Factory Droid

Connect Factory's Droid CLI to RealRelay.ai with a custom model in ~/.factory/settings.json: install it, add the model, check the connection and choose models.

Create an API keyBrowse the catalog
Protocol
OpenAI Chat Completions · Anthropic Messages · OpenAI Responses
Base URL
https://www.realrelay.ai/v1
Official docs
docs.factory.com
Checked against the tool’s docs
2026-10

Overview

Droid is Factory's coding agent for the terminal (there is also a desktop app). It reads your codebase, proposes diffs and waits for your approval before it edits. Its bring-your-own-key custom models can speak three protocols. For most models, use the generic Chat Completions provider and RealRelay.ai's /v1/chat/completions endpoint. Claude models can use /v1/messages, and the few Responses-only models use /v1/responses.

  • An API key from the API keys page of the console.

  • The base URL with /v1 for the Chat Completions and Responses providers, and without it for the Anthropic provider.

  • A model ID exactly as GET /v1/models lists it, for example z-ai/glm-5.2.

Factory says it fully tests only Anthropic and OpenAI models on their official APIs, and does not guarantee that every custom model works out of the box. Your key stays on your machine; custom models work in the Droid CLI and desktop app, not in Factory's web or mobile apps.

Install

Use one of Factory's install methods. On Linux, Factory also asks for the xdg-utils package.

macOS · Linux
curl -fsSL https://app.factory.ai/cli | sh
Homebrew
brew install --cask droid
Windows PowerShell
irm https://app.factory.ai/cli/windows | iex
npm
npm install -g droid

Run droid in a project folder. If it asks you to sign in, finish the browser sign-in to your Factory account first.

Configure

  1. 1

    Put the key in your environment

    The settings file refers to the key by variable name, so the key itself never sits in the file. Replace sk-*** with your key.

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"

    Run source ~/.zshrc, or open a new terminal.

    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")

    Close and reopen the terminal afterwards.

  2. 2

    Add the custom model

    Add an entry to the customModels array in ~/.factory/settings.json. If the file already has other settings or custom models, merge the entry in instead of replacing the file. Droid picks up the change without a restart.

    ~/.factory/settings.json
    1{2  "customModels": [3    {4      "model": "z-ai/glm-5.2",5      "displayName": "RealRelay",6      "baseUrl": "https://www.realrelay.ai/v1",7      "apiKey": "${REALRELAY_API_KEY}",8      "provider": "generic-chat-completion-api",9      "maxContextLimit": 200000,10      "maxOutputTokens": 3200011    }12  ]13}
    ~/.factory/settings.json
    1{2  "customModels": [3    {4      "model": "anthropic/claude-sonnet-4-6",5      "displayName": "RealRelay Claude",6      "baseUrl": "https://www.realrelay.ai",7      "apiKey": "${REALRELAY_API_KEY}",8      "provider": "anthropic",9      "authMode": "bearer",10      "maxContextLimit": 200000,11      "maxOutputTokens": 3200012    }13  ]14}
    ~/.factory/settings.json
    1{2  "customModels": [3    {4      "model": "openai/gpt-5.3-codex",5      "displayName": "RealRelay Codex",6      "baseUrl": "https://www.realrelay.ai/v1",7      "apiKey": "${REALRELAY_API_KEY}",8      "provider": "openai",9      "maxContextLimit": 200000,10      "maxOutputTokens": 3200011    }12  ]13}

  • provider picks the protocol. generic-chat-completion-api is Chat Completions, anthropic is Anthropic Messages and openai is the Responses API. Factory recommends the generic provider for anything that is not OpenAI's or Anthropic's own API.

  • "apiKey": "${REALRELAY_API_KEY}" makes Droid read the key from the environment variable of that name.

  • authMode: "bearer" makes the Anthropic provider send the key as Authorization: Bearer, the same as every other RealRelay.ai endpoint.

  • maxContextLimit and maxOutputTokens tell Droid the model's limits, which it cannot read from RealRelay.ai. Details under Models.

  • You can add the same entry from Droid instead: run /settings and open Custom models, or run /model and choose Manage custom models. In the desktop app it is Settings → Custom Models.

Verify

  1. 1

    Call the endpoint directly

    Run this in the terminal where the key is set. A JSON reply with a choices array means the address, key and model work.

    Terminal
    1curl -sS "https://www.realrelay.ai/v1/chat/completions" \2  -H "Authorization: Bearer $REALRELAY_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"model": "z-ai/glm-5.2", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'
  2. 2

    Run one prompt

    droid exec refers to a custom model as custom:, its display name with spaces turned into dashes, and its position in customModels counting from 0. If RealRelay is not your first custom model, change the number.

    Terminal
    droid exec --model "custom:RealRelay-0" "Reply with OK"
  3. 3

    Pick it in a session

    Start droid, run /model and choose RealRelay under Custom Models. Send a short message; the reply, and the request in the console's usage logs, confirm the whole path.

    Droid
    cd /path/to/your/projectdroid/model

Models

Each RealRelay.ai model you want is its own entry in customModels, with its own displayName. Switch between them with /model.

Set maxContextLimit to the model's context window from its catalog page, minus maxOutputTokens if the window counts output too. If you leave it out and Droid does not know the model, it assumes 250,000 tokens or your compaction limit, whichever is higher, which is too much for smaller models. Droid compacts the conversation to stay within it. A larger value does not make Droid compact later, though: compaction still starts at 250,000 tokens by default, and you raise that in /settings (keep it below maxContextLimit). The example values are safe for the models named here.

Factory notes that models below about 30B parameters do much worse at agentic coding. Choose a model with tool calling and a large context window; see Choosing a model.

Troubleshooting

  • The model does not appear under Custom Models. settings.json is not valid JSON, or a required field (model, baseUrl, provider) is missing.

  • "Invalid provider". provider must be exactly generic-chat-completion-api, anthropic, openai or bedrock-converse.

  • 401 or another authentication error. REALRELAY_API_KEY is not set in the environment Droid was started from, or the key is wrong. Open a new terminal and start Droid again.

  • 404. The base URL form does not match the provider: the Anthropic provider takes the site address without /v1, the other two need it.

  • Errors naming the model with the openai provider. That provider uses Responses, which RealRelay.ai serves for only a few models. Use generic-chat-completion-api for everything else, including plain openai/gpt-5.x.

  • Images are ignored. Droid turns image input off for the generic provider by default. Set "noImageSupport": false only if the model accepts images.