> For the complete documentation index, see [llms.txt](https://docs.darcyiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.darcyiq.com/dispatch/use-dispatch/cookbooks.md).

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

{% hint style="info" %}
**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.
{% endhint %}

## 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](/dispatch/use-dispatch/api-keys.md).                                       |
| **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](/dispatch/use-dispatch/models.md).                                                                      |

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

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

{% hint style="warning" %}
**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.
{% endhint %}

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.

{% hint style="warning" %}
**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.
{% endhint %}

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.

{% hint style="warning" %}
**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.
{% endhint %}

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](/dispatch/use-dispatch/api-keys.md)    |
| Choose which tier to put in your config | [Models](/dispatch/use-dispatch/models.md)        |
| Walk through a first request end to end | [Quickstart](/dispatch/get-started/quickstart.md) |
| Watch your tool's requests arrive       | [Overview](/dispatch/use-dispatch/overview.md)    |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.darcyiq.com/dispatch/use-dispatch/cookbooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.