Integrate the Martian Gateway With Claude Code

This document describes how to set up Claude Code to route all your LLM requests through the Martian Gateway.

Ensure you have your Martian API key from the Martian Dashboard before continuing.

Prerequisites

Ensure you have Claude Code installed. See the Claude Code quickstart for more options, or use one of the following:

curl -fsSL https://claude.ai/install.sh | bash

Configuration

Use the bare origin https://api.withmartian.com. Claude Code appends /v1/messages to ANTHROPIC_BASE_URL. Configure ANTHROPIC_AUTH_TOKEN so Claude Code sends your Martian key as a Bearer token.

Choose one of the following configuration methods:

Option 1: Global Configuration

Create or edit ~/.claude/settings.json. This configuration applies to Claude Code in every project:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.withmartian.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-martian-key"
  }
}

Replace sk-your-martian-key with your key from the Martian Dashboard.

Claude Code does not expand ${VARIABLE} references inside the env block. Enter the credential directly, export it in your shell as shown below, or use Claude Code's apiKeyHelper with a secret manager. Never commit a settings file containing a key.

Credentials entered directly in settings files or shell commands are stored in plaintext and may appear in local shell or Claude Code history. Prefer a secret manager for shared machines, and rotate any key exposed during setup.

Option 2: Shell Environment

Export the values before starting Claude Code:

export ANTHROPIC_BASE_URL="https://api.withmartian.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-martian-key"
claude

Add the exports to your shell profile if you want new terminal sessions to inherit them.

To select a specific model, set ANTHROPIC_MODEL to its full Martian model ID from Available Models.

Option 3: Secret Manager or Rotating Key

Use Claude Code's apiKeyHelper when your key is stored in a secret manager or rotates automatically. The helper command must print only the current key to standard output.

For example, with the 1Password CLI:

{
  "apiKeyHelper": "op read 'op://Private/Martian API Key/credential'",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.withmartian.com"
  }
}

Replace the op read command with the equivalent command for your secret manager. Do not also set ANTHROPIC_AUTH_TOKEN; Claude Code uses the helper output as the request credential and refreshes it periodically or after an HTTP 401 response.

apiKeyHelper runs through /bin/sh, which does not load ~/.zshrc or ~/.bashrc. The helper must be a self-contained command that can authenticate to the secret manager without relying on a shell-profile export.

Verify Your Setup

Confirm your credential with a direct Messages request using a currently available Claude model:

curl https://api.withmartian.com/v1/messages \
  -H "Authorization: Bearer sk-your-martian-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-20250514",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

After a successful response, start Claude Code and run /status to confirm the base URL and credential source.

Troubleshooting

  • Claude Code asks you to log in: Ensure ANTHROPIC_AUTH_TOKEN is available before first-run setup. Global ~/.claude/settings.json is the most reliable location.
  • A settings change is not reflected: Restart Claude Code and confirm the intended environment values were loaded when the session started.
  • apiKeyHelper cannot find a shell variable: Helpers run through /bin/sh and do not load ~/.zshrc or ~/.bashrc. Use a self-contained secret-manager command rather than relying on a shell-profile export.
  • A model returns 404: Set ANTHROPIC_MODEL to the full ID shown on Available Models.
  • A direct request returns 401: Recheck the key and ensure it is sent as Authorization: Bearer.
  • A direct request returns 402: Add credits in the Martian Dashboard.

Next Steps

View Available Models

Browse 200+ AI models from leading providers with real-time pricing.

Read more

View Other Integrations

Explore other ways to integrate the Martian Gateway with your development workflow.

Read more