--- title: How to route your coding agent spend through AI Gateway description: Point Claude Code, Codex, Cursor, and every other harness on your machine at AI Gateway with one CLI command, on a budgeted key, so all of your coding agent spend lands in one place. url: /kb/guide/route-coding-agent-spend-through-ai-gateway canonical_url: "https://vercel.com/kb/guide/route-coding-agent-spend-through-ai-gateway" published: 2026-08-26 last_updated: 2026-08-26 authors: William Armstrong related: - /docs/ai-gateway - /docs/cli - /docs/ai-gateway/coding-agents - /docs/ai-gateway/authentication-and-byok - /docs/ai-gateway/models-and-providers/routing-rules - /docs/ai-gateway/observability-and-spend install_vercel_plugin: npx plugins add vercel/vercel-plugin --- ## Related pages > **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below. - [vercel ai-gateway](https://vercel.com/docs/cli/ai-gateway?from=related) — Manage AI Gateway resources from the Vercel CLI: API keys, routing rules, models, and coding agent setup. - [Migrate to AI Gateway](https://vercel.com/docs/ai-gateway/getting-started/migrate-to-ai-gateway?from=related) — Move your app's model calls to Vercel AI Gateway with a single coding-agent prompt, whatever provider or SDK you use tod - [Budgets](https://vercel.com/docs/ai-gateway/observability-and-spend/budgets?from=related) — Cap AI Gateway spend for your team, a single project, or an individual API key with budgets, refresh periods, spend aler - [Pricing](https://vercel.com/docs/ai-gateway/pricing?from=related) — Learn about pricing for AI Gateway. - [Claude Code](https://vercel.com/docs/ai-gateway/coding-agents/claude-code?from=related) — Use Claude Code and the Claude Agent SDK with AI Gateway. - [How I use OpenCode with Vercel AI Gateway to build features fast](https://vercel.com/kb/guide/how-i-use-opencode-with-vercel-ai-gateway-to-build-features-fast?from=related) — How to route different AI models to different coding tasks automatically, cutting token costs by ~70% without losing qua - [How to build your own AI model router](https://vercel.com/kb/guide/how-to-build-your-own-ai-model-router?from=related) — Build an AI model router with Vercel AI Gateway. Keep routing, key, and retention decisions in your code while the gatew - [Build AI agents with AI Gateway and AI SDK](https://vercel.com/kb/guide/ai-gateway-and-ai-sdk?from=related) — Build AI agents on Vercel with AI Gateway and AI SDK, then make them reliable, capable, and durable with Sandbox, Chat S - [The Complete Guide to Vercel Agent](https://vercel.com/kb/guide/vercel-agent?from=related) — Learn what Vercel Agent does, how to set up Code Review, Investigation, Chat, and Installation, and what each feature co Full cross-link map for this page: [/kb/guide/route-coding-agent-spend-through-ai-gateway.graph.md](/kb/guide/route-coding-agent-spend-through-ai-gateway.graph.md) Running several coding agents means several provider keys, invoices, and dashboards. This makes it hard to say what coding agents cost last month or which tool did the spending. Routing every agent through [AI Gateway](https://vercel.com/docs/ai-gateway) fixes that by giving each one gets a gateway base URL and a shared gateway API key/ Then, requests land on a single endpoint with one budget, one set of request logs, and one bill. The Vercel CLI does the wiring for you, detecting the agents on your machine, provisioning the key, and writing each config file. After this guide, all of your agentic spend, across your own machine and your team's workspace, is managed and visible in your AI Gateway dashboard. You get transparency, clarity, and control over your team's AI spend. ## Prerequisites Before you begin, ensure you have: - [Vercel CLI](https://vercel.com/docs/cli) installed and authenticated with `vercel login` - A [Vercel account](https://vercel.com/signup) and a team you can create AI Gateway API keys in - At least one [supported coding agent](https://vercel.com/docs/ai-gateway/coding-agents) installed locally ## How it works The CLI does three things in one pass. It creates an AI Gateway API key, which becomes the unit of accounting since every agent shares it. It writes the right base URL for each agent, since the gateway exposes several compatibility surfaces and each harness speaks a different protocol. And it edits each agent's config file in place, preserving formatting and saving a `.bak` first. Your model picker is untouched. ## Run the setup command Start with no flags at all. The command asks for everything it needs, and the prompts double as a tour of what is being configured: ```bash vercel ai-gateway coding-agents setup ``` It walks you through the following, in order: 1. **Which agents to configure.** The agents already installed on your machine are pre-selected. Deselect anything you want to leave alone. 2. **Consent** for any agent carrying a pre-flight warning, meaning connecting it could disrupt an existing setup. Declining skips that agent and continues with the rest. 3. **Session migration**, if you have Claude Desktop or Codex Desktop sessions that would otherwise vanish from the switched provider. Originals are never moved or deleted, only copied. 4. **A name for the API key.** The prompt suggests something like `['s ] Coding Agents`. Take it, or name it after the machine. This name is what you will be reading in the request logs later, so make it identifiable. 5. **The team that owns the key.** This is the team the spend bills to. 6. **A spend limit** for the key, in US dollars. 7. **An expiration** for the key. 8. **Keychain storage** on macOS. Say yes. The key goes into your login Keychain instead of sitting in plaintext config, and the agents read it through a shell export. The command then prints a summary and the planned changes as a per-file diff, with the key masked. Confirm to write the files. Decline and it writes nothing and never creates a key, so the confirmation step is a safe place to change your mind. Open a new terminal afterward so the shell exports load, and restart Claude Code so it picks up the new settings. That is the whole setup. Everything below is for when you want to skip the prompts, script the run, or change a decision you made during it. ## Choose which agents to connect By default the command configures the agents it detects, meaning the ones whose config directory already exists. To be explicit instead, name each agent with a repeatable `--agent` flag: ```bash vercel ai-gateway coding-agents setup --agent claude-code --agent codex ``` The `--agent` values are `claude-code`, `cline`, `codex`, `cursor`, `hermes`, `kilo`, `openclaw`, `opencode`, and `pi`. Pass `--all` to configure every supported agent whether or not it is installed yet, which is useful on a machine you are about to install more coding agents on. Naming an agent explicitly also grants consent for that agent's warnings in a run without prompts, so `--agent` is the flag to reach for when a detected agent gets skipped with reason `requires_consent`. Four agents behave slightly differently and are worth knowing about before you run it: - **Cursor** keeps API key settings in its account-synced store, so there is no file to write. The command exports the key and prints the steps to finish in **Settings** -> **Models**, including the base URL to paste. - **Cline, Hermes, and OpenClaw** cannot start without a model, so they get `anthropic/claude-fable-5` as a starting point, which you can change at any time. For Claude Code, Codex, OpenCode, Pi, Kilo Code, and Cursor the command pins no model, so you keep choosing your own inside the agent. ## Answer the prompts up front with flags Every prompt has a matching flag, so you can supply the answers in the command instead of typing them. Add `--yes` to skip the prompts entirely, which turns the run fully non-interactive: ```bash vercel ai-gateway coding-agents setup \ --scope my-team \ --name "MacBook Coding Agents" \ --budget 1000 \ --refresh-period monthly \ --expiration 90d \ --yes ``` | Flag | Values | Notes | | --------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--scope ` | Your team slug | The team that owns the new key. `--team` is an alias. Without one, and without a currently selected team, the run fails with reason `missing_scope` (no team was selected for the new key) | | `--budget ` | Any number, minimum 1 | Omit it and the key is unlimited | | `--refresh-period ` | `daily`, `weekly`, `monthly`, `none` | Omit it and you get a one-time limit with no reset | | `--expiration ` | `7d`, `30d`, `60d`, `90d`, `1y`, `none` | Defaults to `none` | | `--name ` | Any string | Omit it and the server assigns one. Name it after the machine so the request logs stay readable | | `--include-byok` | Boolean | Counts [bring-your-own-key](https://vercel.com/docs/ai-gateway/authentication-and-byok) usage toward the quota. Off by default | | `--key ` | An existing `vck_` key | Skips key creation and the name, team, budget, and expiry prompts entirely | - `--refresh-period` is the flag most worth being deliberate about, because leaving it off does not give you a monthly cap by default. It gives you a one-time allowance that never refills, which is a different thing than what most people think they are setting up. Pick the cadence to match how you want the ceiling to behave. A monthly refresh gives each machine a recurring allowance. `daily` is the tighter choice when you are trying to catch a runaway loop rather than budget for a month, since a stuck agent burns through a daily cap in hours and stops there instead of eating the month. Budgets are a soft cap checked at the start of each request, so the request that crosses the line still finishes and you never get a truncated response. After that the gateway returns HTTP 402 and rejects further requests on that key until the budget resets or you raise it. - `--include-byok` applies to provider keys you already had before AI Gateway, like an Anthropic or OpenAI key with credit on it, that you have added to the gateway. Requests using those keys are billed by that provider rather than by Vercel, so by default they show up in your request logs but do not draw down the budget you set here. Add the flag if you want this budget to cap all agent spend, including the credit you are burning at those providers. ## Decide where the key is stored Say yes to the Keychain. It is the macOS default, it keeps the key out of your config files, and each agent reads it through a shell export at terminal startup. - `--no-keychain` writes the key into the agent config files and your shell startup file instead. That is automatic on non-macOS hosts and the fallback if a Keychain write fails. ```bash vercel ai-gateway coding-agents setup --no-keychain ``` The risk there is a plaintext key in your shell startup file. If you keep dotfiles in git, that key gets committed the next time you sync, so check whether the file is tracked before you run it. Pair the run with a short `--expiration` and a `--budget` so a leaked key stops working on its own and cannot run up an open tab, and use `--shell-rc ` to put the export block in an untracked file that your tracked one sources. Two caveats either way. Pi always keeps the key in its own auth file, and Cline stores it in its provider config rather than reading it from the shell, so running either means a plaintext key on disk regardless. And the command uses a single Keychain item, so connecting a second team replaces the stored key rather than adding to it. ## Preview before you write Add `--dry-run` to see the exact edits without creating a key or touching a file: ```bash vercel ai-gateway coding-agents setup --dry-run ``` A dry run is the right first move on a machine with an unusual setup, since it surfaces which agents were detected and which config files the command intends to edit before anything is provisioned. On a Keychain setup the confirmation prompt offers a third option: hand the edits to a coding agent you already have open instead of writing them yourself. The command copies a prompt describing the exact changes to your clipboard, and because the key stays in the Keychain that prompt carries no secret. `--apply prompt` picks it without asking, and `--apply edit` is the default that writes the files. ```bash vercel ai-gateway coding-agents setup --apply prompt --scope my-team --yes ``` The `--scope` is required whenever you pass `--yes`, since there is no prompt left to ask which team owns the key. Drop it only if you have already selected a team with `vercel switch`. Otherwise the run fails with reason `missing_scope`, reporting that no team was selected for the new key. ## Roll it out across a team Putting your whole team's AI spend through AI Gateway lets you govern and manage it in one place. To get there, run this setup from an onboarding script so every new machine is configured the same way without anyone doing it by hand. For onboarding scripts and machine provisioning, combine `--yes` with `--non-interactive` to get a single JSON object back instead of human-readable output: ```bash vercel ai-gateway coding-agents setup \ --scope my-team \ --budget 1000 \ --refresh-period monthly \ --expiration 1y \ --non-interactive \ --yes ``` The `--scope` here is not optional. Pass it explicitly in a script rather than relying on whatever team the machine happens to be pointed at. The JSON payload reports which files were configured, which agents were skipped, and a `reason` code your script can branch on. Treat it as a secret, since a successful run returns the full API key unmasked. Give every machine its own key rather than sharing one. The dashboard then reads as a list of machines, so you can see who is driving spend, cap one machine, or revoke a single key when a laptop is lost. Pair that with two ceilings above the individual keys. A team-wide limit caps total spend no matter how many keys exist, and a per-key default makes sure keys created outside this flow still arrive with a limit rather than unlimited: ```bash vercel ai-gateway budgets set team --limit 20000 --refresh-period monthly vercel ai-gateway budgets defaults set api-key --limit 200 ``` ## Verify the traffic is routing through the gateway Open a new terminal, run a prompt in one of the connected agents, then check that the request arrived: ```bash vercel ai-gateway api-keys inspect ``` Find the ID with `vercel ai-gateway api-keys ls`. The output shows the key's quota, current spend, alert thresholds, and expiry. A non-zero spend figure is your confirmation that the harness is pointed at the gateway and not still talking to its provider directly. The [AI Gateway dashboard](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway&title=Go+to+Dashboard) is where the picture gets useful. AI Gateway logs every request, so you can watch latency and token usage, break spend down by model, user, or tag, and track credit balances in one place. The Requests section groups usage by project and by API key alongside a detailed log of every request, and each summary carries request count, average tokens, P75 duration, P75 TTFT, and cost for the time frame you pick. The API key grouping is the view this whole setup exists to unlock. Because every harness on a machine shares one key, that row answers what coding agents cost you, and the per-request log underneath it tells you which models did the spending. ## Rotate the key or switch teams On a machine that is already set up, running the command again changes nothing. It asks whether you want to reconfigure, and answering no exits successfully with reason `already_configured`. Because no new key is created, you can safely leave the command in a bootstrap script without piling up unused keys. To actually make a change: - `--reconfigure` runs the full setup again, which is how you rotate the key or move the machine to a different team. - `setup --key ` on a Keychain setup swaps in a rotated or expired key, refreshing the Keychain entry in place without touching any config file. ```bash vercel ai-gateway coding-agents setup \ --reconfigure \ --scope my-team \ --budget 2000 \ --refresh-period monthly \ --yes ``` ## Next steps - **Constrain which models agents can reach.** [Routing rules](https://vercel.com/docs/ai-gateway/models-and-providers/routing-rules) let you rewrite a request for one model into another, or deny a model outright, at the team level. Rewriting an expensive default down a tier is a spend lever that requires no change on any developer's machine. - **Break spend down further.** The [Custom Reporting API](https://vercel.com/docs/ai-gateway/observability-and-spend) groups cost and token consumption by model, user, tag, or provider, which is how you get from a per-key total to per-person or per-project attribution. - **Set spend alerts.** Keys created with `vercel ai-gateway api-keys create` accept `--alert-thresholds 75,100`, so you hear about a cap before it starts rejecting requests.