Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Cookbooks

Step-by-step setup for Claude Code, Codex, Cursor, OpenCode, VS Code, Kilo Code and plain HTTP, with each tool's caveats

The Cookbooks page shows you how to point the tools your team already uses at Dispatch. There's a guide for each supported coding agent and editor, plus a plain HTTP request for scripts and your own code. Every guide is filled in with your organization's base URL and tiers, so you can copy the snippets and use them as they are, apart from adding your key.

This page summarizes each guide and, more importantly, the catch each tool has. Use the in-console guide for the exact, copyable configuration.

Using a tool that isn't listed? Anything that accepts an OpenAI-compatible base URL works with Dispatch. Start from the HTTP request guide and use the same three values: base URL, key and tier.

The General Recipe

Every tool needs the same three things.

Value
Where to get it
Notes

Base URL

Cookbooks → Getting started → Base URL

Ends in /v1. Dispatch speaks both OpenAI Chat Completions and Anthropic Messages at this address, so most tools only need this one value overridden. Copy it rather than typing it.

API key

API keys → Create key

Starts with dr_live_. Shown once, when you create it. Send it as Authorization: Bearer. See API Keys.

Model

Cookbooks → Getting started → Model tier, or the Models page

A tier id, never a raw model name. Raw model names are rejected. See Models.

For a script or your own code, set them as environment variables and check the key before involving any tool:

export DARCY_BASE_URL="<Base URL from the Cookbooks page>"
export DARCY_API_KEY="dr_live_your_key_here"
export DARCY_MODEL="<tier id>"

# Lists the tiers your key can call. Costs nothing.
curl $DARCY_BASE_URL/models \
  -H "Authorization: Bearer $DARCY_API_KEY"

# Sends a message.
curl $DARCY_BASE_URL/chat/completions \
  -H "Authorization: Bearer $DARCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "<tier id>", "messages": [{"role": "user", "content": "Say hello"}]}'

A list of tiers means the key works. A 401 means the key never arrived, and a 404 usually means a doubled /v1.

Getting Started

The page opens on Getting started, which sets out the four things every guide assumes:

  1. Base URL, with a copy button.

  2. API key — your newest key, masked, with Create key or Manage keys. If you don't have one yet, it says "No key on this account yet".

  3. Model tier — your callable tiers. Click one and every snippet in every guide follows it. Auto is selected by default when your organization has it. Tiers that are switched off for you aren't offered here.

  4. Check it works — the model-list request above, with what a working reply looks like.

Copy as .env copies the base URL, a key placeholder and your chosen tier as KEY=value lines, ready for an .env file, a container or a CI secret.

Under the tiles, Limits lists each tier's context window, maximum reply, whether it accepts images, and the reasoning levels it supports. These are the floor across the models behind a tier, because a request can land on any of them. When every tier has the same limits, Dispatch says so once. Compare tiers opens the Models page.

Features Every Guide Shares

  • Requirement chips under each guide's title give the setup time, anything you need first, and which API the tool speaks.

  • OS tabs switch the snippets between operating systems, for the tools whose setup differs by platform. Your choice carries across guides.

  • Copy all steps copies the whole guide as instructions you can paste into the coding agent you already have open. The steps name your tier and its limits, and the agent will ask you for your key rather than guessing one.

  • Next at the foot of each guide moves to the next one. If a tool won't connect, the HTTP request guide tests your key with no tool in the way.

Supported Tools

Guide
Setup time
Requirements
Speaks

HTTP request

~1 minute

—

OpenAI Chat Completions

Claude Code

~3 minutes

Needs Node 18+

Anthropic Messages

Codex

~4 minutes

Desktop or CLI

OpenAI Responses

Cursor

~2 minutes

Settings UI, no file

OpenAI Chat Completions

OpenCode

~3 minutes

Needs Node 18+

OpenAI Chat Completions

VS Code

~4 minutes

Needs Copilot Chat

OpenAI Chat Completions

Kilo Code

~4 minutes

Global config only

OpenAI Chat Completions

In the list on the left, Claude Code is flagged Setup differs and Cursor is flagged Has limits.

HTTP Request

The quickest way to a working call, and the quickest way to tell a Dispatch problem from a misconfigured tool. The guide has two steps:

  1. Check your key works — a minimal chat request to your chosen tier. A reply means the key, the base URL and the tier are all right, so anything still failing in a tool is that tool's configuration.

  2. Reasoning and sampling — the same request with reasoning effort, temperature and top-p set. Every inference parameter is forwarded as sent. Only the model and Dispatch's own routing fields are rewritten, and the model's reasoning comes back unchanged. The guide lists the reasoning levels your chosen tier accepts.

Claude Code

You point the Claude Code CLI at Dispatch with a block of environment variables. Nothing else in your setup changes.

  1. Install the CLI with npm or the native installer. Any version that supports gateway discovery works.

  2. Add the environment variables to your shell profile, or to your PowerShell profile on Windows, then open a new terminal. They set the base URL, your key as the auth token, an empty Anthropic API key, model discovery, and your tier for each of Claude Code's model classes.

  3. Or put the same settings in .claude/settings.local.json in your project instead.

  4. Run claude, then /status. It should report the auth token as ANTHROPIC_AUTH_TOKEN and the base URL as Dispatch's, and /model should list your tiers under From gateway.

Claude Code's base URL must not include /v1. Claude Code is the one tool that adds /v1 itself. Give it the base URL with /v1 removed, or every call returns a 404. The guide shows the correct value next to the wrong one.

Other caveats, as the guide states them:

  • The four model lines are not optional. Claude Code picks a model for each task class using Anthropic's own names, including for background work like naming your conversation. Any class left unmapped sends a model Dispatch doesn't recognize. The symptom is a session that works and then fails on an unrelated turn.

  • Tiers appear as anthropic/<tier id> in /model, because Claude Code discards any model name without "anthropic" or "claude" in it. It's the same tier, and Dispatch accepts either spelling.

  • Claude Code assumes a 200,000-token window for any model it doesn't recognize, and discovery doesn't tell it otherwise. The snippet sets CLAUDE_CODE_MAX_OUTPUT_TOKENS and CLAUDE_CODE_AUTO_COMPACT_WINDOW from your tier wherever it can, because those are the only corrections Claude Code honours. Image support can't be declared at all; check the tier's Limits.

  • Don't use a .env file. Claude Code doesn't read one.

  • If you see "model not found", or usage bills an Anthropic account, a saved Anthropic login is still in play. Run /logout inside Claude Code, then quit and relaunch.

Codex

One provider block and your key. The guide has Desktop and CLI tabs, because Codex Desktop also needs a catalog file.

Codex CLI: install it with npm, add the provider block to ~/.codex/config.toml, and run codex. Each of your tiers gets a profile; pick one to switch.

Codex Desktop: install the app from openai.com/codex (not the npm CLI), save the catalog file the guide provides (with Download) to the path shown, add the provider block to ~/.codex/config.toml, then fully quit Codex, including the tray icon, and reopen it.

Caveats, as the guide states them:

  • Keep wire_api = "responses". Codex dropped "chat" in early 2026, so an older guide that names it produces a config Codex refuses to load.

  • Put your key in experimental_bearer_token. That field is the secret itself. Don't put the key in env_key, which is a variable name.

  • Desktop can't discover Dispatch on its own. It's logged into ChatGPT, so it refreshes OpenAI's catalogue rather than Dispatch's. The catalog file is what gives the picker your tiers. Re-download it when a tier is added or re-pointed. It replaces Codex's built-in list rather than merging with it.

  • On Desktop, web_search = "disabled" and model_context_window must stay above every [section]. Pasted at the bottom, they belong to the section above and do nothing. Desktop then runs web search by calling Dispatch, which doesn't host it, and every prompt after the first search in that thread fails. Also delete any [tools] block with web_search = true.

  • On the CLI, model_context_window belongs at the top level. Inside the provider section it's ignored.

  • The Desktop picker may still say Custom. That's expected. Requests use the active profile.

Cursor

Dispatch stands in for Cursor's OpenAI key. Chat and agent requests route to Dispatch; several things don't.

  1. Open Cursor Settings (Ctrl/Cmd + ,), go to Models, and expand API Keys.

  2. Turn on OpenAI API Key and paste your dr_live_ key. Cursor labels the field OpenAI, but the key is yours and is billed through Dispatch.

  3. Turn on Override OpenAI Base URL and set it to the base URL exactly, including the trailing /v1.

  4. Click + Add model, enter each tier id, and pick it from the model dropdown in chat.

Cursor works, with limits. Tab completion never routes to Dispatch. Cursor's Verify button tests a built-in OpenAI model that Dispatch will refuse, so a failed verification doesn't mean your setup is wrong. Confirm it works by sending a message instead.

Cursor also can't be told your tier's limits, as the guide explains:

  • Cursor assumes a 1,000,000-token context for a custom model and has no setting to change it. A long session can fail at your tier's real limit before Cursor thinks compaction is due. If that happens, switch to Auto mode to let it compact, then switch back.

  • Image attachments don't reach Dispatch at all. Cursor checks requests with images against OpenAI directly and never applies your base URL override to them. Use another tool if you need either of these.

OpenCode

A provider block plus a discovery plugin. This is the one setup that keeps your limits up to date on its own.

  1. Install OpenCode with the install script, or with npm on Windows.

  2. Put the provider block in ~/.config/opencode/opencode.json for every project, or opencode.json in one project's root.

  3. Run opencode in your project. Run /models to switch tiers. They appear under Darcy Dispatch after the first launch downloads the plugin. If none appear, quit OpenCode fully and reopen it.

Caveats, as the guide states them:

  • Keep the plugin line. OpenCode doesn't read Dispatch's tier list by itself; the plugin fetches it on startup.

  • Don't list the tiers under models. A list that names them replaces discovery, and new tiers never appear. The one exception is setting a reasoning level for a tier, which the guide shows how to do.

  • Keep modelInfoFormat. It's what gives OpenCode each tier's real context window, reply limit and image support. Without it, OpenCode quietly replaces every image you attach with an error, and the model replies that it can't see images on a tier that accepts them.

  • You don't need to set a reasoning level. Dispatch applies the tier's own default to any request that names none.

VS Code

Uses Copilot Chat's Custom Endpoint provider, with your tiers listed as models.

  1. In the Chat view, open the model picker and choose Manage Language Models, or run Chat: Manage Language Models from the Command Palette. Select Add Models → Custom Endpoint, name the group Darcy Dispatch, and pick Chat Completions.

  2. Paste the provider block into the chatLanguageModels.json file VS Code opens. Merge it into the array if other providers are already there.

  3. Pick a Darcy Dispatch model in the Chat picker. VS Code asks for your key the first time. Restart VS Code if the models don't appear.

Chat and agent only. Inline completions never route to Dispatch, and semantic search still needs a GitHub account. Copilot Business and Enterprise users also need their admin to enable Bring Your Own Language Model Key in the Copilot policy on GitHub.

Other caveats, as the guide states them:

  • Don't use the deprecated customoai vendor. Current VS Code ignores it.

  • Leave the key placeholder in the file as it is. VS Code prompts for the key and stores it. Pasting your key into the file puts it in plain text next to your settings.

  • The tiers are listed rather than discovered, so image attachments and the tier's real window are honoured. A new tier needs a new entry.

  • Keep toolCalling set to true. Agent mode hides any model that doesn't declare it.

Kilo Code

A provider in Kilo Code's global config, with each tier's capabilities written out.

  1. Install Kilo Code from the VS Code Marketplace, or install the CLI with npm. Both read the same config file.

  2. Put the provider block in Kilo Code's global config file, at the path the guide shows for your operating system.

  3. Set your key in the DARCY_API_KEY environment variable, somewhere that survives a new terminal. On Windows, restart VS Code afterwards.

  4. Pick a tier from Kilo Code's model picker, under Darcy Dispatch. If none appear, quit Kilo Code fully and reopen it.

Caveats, as the guide states them:

  • Don't put the config in a project kilo.jsonc. The key variable only resolves in a trusted config. In a repository it's ignored, and the provider looks configured but sends no key.

  • Keep the npm line. Without the OpenAI-compatible adapter, the provider starts and then offers no models. In the Providers UI, pick OpenAI Compatible, not OpenAI Responses.

  • The models map is required. Without it, Kilo Code leaves every capability unset, which disables compaction and turns off image attachments. A new tier needs a new entry.

Next Steps

Goal
Documentation

Create the key your tool will use

API Keys

Choose which tier to put in your config

Models

Walk through a first request end to end

Quickstart

Watch your tool's requests arrive

Overview

PreviousModels
NextCost Reporting

Last updated

Was this helpful?