Skip to main content

Configure coding tools with the tetrate CLI

tetrate agentrouter integrate sets up popular AI coding tools to send their model calls through a Tetrate Agent Router gateway, using existing Agent Router credentials. Instead of copying a base URL and API key into each tool by hand, one command reads the logged-in session and writes the tool's config.

Persona: Developer configuring a local coding tool against an Agent Router gateway.

Estimated time: 5 to 10 minutes once the CLI is installed and authenticated.

Outcomes​

By the end of this guide:

  • The tetrate CLI is installed and authenticated against the management plane.
  • The data plane (gateway) to route through is identified by its data plane id.
  • At least one coding tool is configured through tetrate agentrouter integrate, optionally previewed with a dry run first.
  • Keys and backed-up config files can be rotated or cleaned up safely.

Prerequisites​

  1. Install the tetrate CLI:

    curl -fsSL https://tare.tetrate.ai/tools/install.sh | bash
    tetrate --version

    The installer verifies the signed release manifest, installs tetrate into ~/.tetrate/bin, and prints the PATH line to add when that directory is not on PATH yet.

  2. Log in so the CLI can reuse the session (data plane, model catalog, and API key):

    tetrate agentrouter api login --base-url https://api.example.tetrate.ai

    --base-url is the management plane API host, not the gateway Base URL shown in the Console. Replace the example with https://api.<tenant>.tetrate.ai, using the same <tenant> hostname segment as the Admin Console (https://dashboard.<tenant>.tetrate.ai) and Console (https://router.<tenant>.tetrate.ai) URLs from the Tetrate provisioning email. The full hostname map is in Self-hosted prerequisites.

    Login can be skipped by passing --gateway-url, --api-key, and --model explicitly, but then nothing is reused from the account.

  3. Know which data plane (gateway) to route through. List them with:

    tetrate agentrouter integrate dataplanes

    Example output:

    DATAPLANE   NAME              GATEWAY URL
    acme-prod   Acme Production   https://acme-prod.gateway.example.com
    acme-dev    Acme Dev          https://acme-dev.gateway.example.com

    --dataplane takes the data plane id from the DATAPLANE column (for example acme-prod), not the display name.

Step 1: list the supported tools​

This command shows every supported tool, whether it is detected on the machine, and where its config file would go:

tetrate agentrouter integrate list

Supported tools include Aider, Claude Code, Claude Desktop (listed as claude-cowork), Cline, Coder, Codex, Continue, Hermes Agent, and OpenClaw.

Step 2: preview a change (dry run)​

tetrate agentrouter integrate <tool> --dry-run --dataplane <name>

The command prints exactly what would be set, with the API key masked, and confirms no file is written.

Claude Code​

tetrate agentrouter integrate claude-code --dry-run --dataplane acme-prod
Detected Claude Code: found `claude` at /Users/you/.local/bin/claude

Claude Code (/Users/you/.claude/settings.json):
set env.ANTHROPIC_BASE_URL = https://acme-prod.gateway.example.com
set env.ANTHROPIC_API_KEY  = sk-test1...
set env.ANTHROPIC_MODEL    = claude-sonnet-5

--dry-run: no changes written.

Codex​

Codex writes two files (config.toml for the provider block, .env for the key):

tetrate agentrouter integrate codex --dry-run --dataplane acme-prod
Detected Codex: found `codex` at /Users/you/.bun/bin/codex

Codex (/Users/you/.codex/config.toml):
/Users/you/.codex/config.toml:
  set model          = gpt-5
  set model_provider = agentrouter
  set [model_providers.agentrouter] base_url/env_key/wire_api
/Users/you/.codex/.env:
  set AGENTROUTER_API_KEY = sk-test1...

--dry-run: no changes written.

Step 3: apply a change​

tetrate agentrouter integrate <tool> --dataplane <name> --yes

For example:

tetrate agentrouter integrate claude-code --dataplane acme-prod --yes

On apply:

  • The command reuses the logged-in session's data plane, model catalog, and API key by default. Override any of them with --gateway-url, --api-key, or --model.
  • It mints a new inference key only if one is not already cached for that profile and data plane; otherwise it reuses the cached key.
  • If a config file already exists, it is backed up (<file>.bak-<timestamp>) before being overwritten.
  • The written file gets 0600 permissions (owner read/write only).
  • After writing, it makes one call to the configured gateway to confirm the key works, and reports the result.

Claude Code: managed mode vs. passthrough mode​

The --passthrough flag applies to Claude Code only. Claude Desktop runs in gateway mode with Agent Router billing; subscription passthrough is not supported there. Passing the flag to another tool raises no error and has no effect, so the traffic is still billed through Agent Router.

tetrate agentrouter integrate claude-code supports two modes:

  • Managed (default). Sets env.ANTHROPIC_BASE_URL, env.ANTHROPIC_API_KEY, and env.ANTHROPIC_MODEL in ~/.claude/settings.json. Every Claude Code call goes through the Agent Router gateway using the issued key.
  • Passthrough (--passthrough). Keeps the existing claude /login session for model calls, so usage is billed to the existing Claude plan. The Agent Router key is only sent as an x-tars-api-key header for attribution; ANTHROPIC_API_KEY is left unset.
tetrate agentrouter integrate claude-code --dataplane acme-prod --passthrough --yes

Trade-off: while managed mode's ANTHROPIC_API_KEY is set, Claude Code disables claude.ai connectors, because an explicit API key takes precedence over the claude.ai login. Choose passthrough mode where connectors are needed, or remove the env block from ~/.claude/settings.json.

For the full Claude Code walkthrough (install, verify with /status, troubleshooting), see Connect Claude Code.

Known issues​

Some newer model names reject temperature=0. Several OpenAI-compatible tools (Aider and similar) default to temperature=0 for any model they do not recognize by name. If the selected model rejects a temperature of 0, the first request fails immediately with an error such as 'temperature' is deprecated for this model, even though the model otherwise works.

Workaround: pin a non-zero temperature for that model in the tool's own per-model settings. For Aider, add an entry to .aider.model.settings.yml with extra_params: {temperature: 1}.

tetrate agentrouter integrate dataplanes prints "No data planes with a configured gateway URL." The command lists the addresses the management plane stores for each data plane: a project gateway URL, or the data plane URL set before 0.7.0. A data plane on 0.7.0 or later that only declares its hostnames in its own chart can be missing from that list even while it serves the project. Since 0.7.0 the command also lists only the calling key's own project's addresses when it runs with an inference key issued for a project other than default.

Workaround: copy an address from the endpoint list the Console shows for the project and pass it with --gateway-url.

Cleanup and rotation​

  • An apply either mints a new inference key or reuses a cached one. Check which before revoking anything: revoking a key still referenced by a tool's config breaks that tool until the integration is re-applied.
  • To rotate a key, revoke the old one (tetrate agentrouter api keys revoke <key-id>), then re-run tetrate agentrouter integrate <tool> --dataplane <name> --yes to mint and write a fresh one.
  • Backed-up config files (<file>.bak-<timestamp>) build up with every apply. Clean them out periodically where the history is not needed.

Where to go next

Connect Claude Code

Verify the session, or fall back to manual env configuration when the CLI path does not fit.

Codex CLI

Add project context so Codex uses Agent Router patterns when it writes application code.