Amp CLI

This guide explains how to use CLIProxyAPI with Amp CLI and Amp IDE extensions, enabling you to use your existing Google/ChatGPT/Claude subscriptions (via OAuth) with Amp's CLI.

Overview

The Amp CLI integration adds specialized routing to support Amp's API patterns while maintaining full compatibility with all existing CLIProxyAPI features. This allows you to use both traditional CLIProxyAPI features and Amp CLI with the same proxy server.

Key Features

• Provider route aliases: Maps Amp's /api/provider/{provider}/v1... patterns to CLIProxyAPI handlers
• Management proxy: Forwards account management requests to Amp's control plane using a secure upstream API key.
• Smart fallback: Automatically routes unconfigured models to ampcode.com
• Security-first: Management routes require API key auth (optional localhost restriction)
• Automatic gzip handling: Decompresses responses from Amp upstream

What You Can Do

• Use Amp CLI with your Google account (Gemini 3 Pro Preview, Gemini 2.5 Pro, Gemini 2.5 Flash)
• Use Amp CLI with your ChatGPT Plus/Pro subscription (GPT-5, GPT-5 Codex models)
• Use Amp CLI with your Claude Pro/Max subscription (Claude Sonnet 4.5, Opus 4.1)
• Use Amp IDE extensions (VS Code, Cursor, Windsurf, etc.) with the same proxy
• Run multiple CLI tools (Factory + Amp) through one proxy server
• Route unconfigured models automatically through ampcode.com

Which Providers Should You Authenticate?

Important: The providers you need to authenticate depend on which models and features your installed version of Amp currently uses. Amp employs different providers for various agent modes and specialized subagents:

• Smart mode: Uses Google/Gemini models (Gemini 3 Pro)
• Rush mode: Uses Anthropic/Claude models (Claude Haiku 4.5)
• Oracle subagent: Uses OpenAI/GPT models (GPT-5 medium reasoning)
• Librarian subagent: Uses Anthropic/Claude models (Claude Sonnet 4.5)
• Search subagent: Uses Anthropic/Claude models (Claude Haiku 4.5)
• Review feature: Uses Google/Gemini models (Gemini 2.5 Flash-Lite)

For the most current information about which models Amp uses, see the Amp Models Documentation.

Fallback Behavior

CLIProxyAPI uses a smart fallback system:

1. Provider authenticated locally (--login, --codex-login, --claude-login):

   • Requests use your OAuth subscription (ChatGPT Plus/Pro, Claude Pro/Max, Google account)
   • You benefit from your subscription's included usage quotas
   • No Amp credits consumed

2. Provider NOT authenticated locally:

   • Requests automatically forward to ampcode.com
   • Uses Amp's backend provider connections
   • Requires Amp credits if the provider is paid (OpenAI, Anthropic paid tiers)
   • May result in errors if Amp credit balance is insufficient

Recommendation: Authenticate all providers you have subscriptions for to maximize value and minimize Amp credit usage. If you don't have subscriptions to all providers Amp uses, ensure you have sufficient Amp credits available for fallback requests.

Architecture

Request Flow

Amp CLI/IDE
  ↓
  ├─ Provider API requests (/api/provider/{provider}/v1/...)
  │   ↓
  │   ├─ Model configured locally?
  │   │   YES → Use local OAuth tokens (OpenAI/Claude/Gemini handlers)
  │   │   NO  → Forward to ampcode.com (reverse proxy)
  │   ↓
  │   Response
  │
  └─ Management requests (/api/auth, /api/user, /api/threads, ...)
      ↓
      ├─ Authenticate with CLIProxyAPI's `api-keys`
      ↓
      ├─ Optional localhost restriction
      ↓
      └─ Reverse proxy to ampcode.com (using `upstream-api-key`)
          ↓
          Response (auto-decompressed if gzipped)

Components

The Amp integration is implemented as a modular routing module (internal/api/modules/amp/) with these components:

1. Route Aliases (routes.go): Maps Amp-style paths to standard handlers
2. Reverse Proxy (proxy.go): Forwards management requests to ampcode.com
3. Fallback Handler (fallback_handlers.go): Routes unconfigured models to ampcode.com
4. Secret Management (secret.go): Multi-source API key resolution with caching
5. Main Module (amp.go): Orchestrates registration and configuration

Configuration

Basic Configuration

Add the ampcode block to your config.yaml (as of v6.5.37, legacy amp-upstream-* keys are auto-migrated and rewritten to this structure on load):

# API keys for clients (e.g., Amp CLI, VS Code) to authenticate with CLIProxyAPI
api-keys:
  - "your-client-secret-key" # Example key for your clients

ampcode:
  # Amp upstream control plane (required for management routes)
  upstream-url: "https://ampcode.com"
  # API key for CLIProxyAPI to authenticate with ampcode.com
  # Get this from https://ampcode.com/settings
  upstream-api-key: "your-ampcode-api-key-goes-here"
  # Optional: restrict management routes to localhost (default: false)
  restrict-management-to-localhost: false
  # Optional: map missing Amp models to local ones
  # model-mappings:
  #   - from: "claude-opus-4.5"
  #     to: "claude-sonnet-4"

Security Settings

API Key Auth for Management Routes

As of v6.6.15, Amp management routes (/api/auth, /api/user, /api/threads, /threads, etc.) are protected by CLIProxyAPI's standard API key authentication middleware.

• If you configure api-keys in config.yaml (recommended), these routes require a valid API key in the request (Authorization: Bearer <key> or X-Api-Key: <key>), otherwise they return 401 Unauthorized.
• After local authentication succeeds, the proxy strips the client's Authorization/X-Api-Key and uses ampcode.upstream-api-key to call the upstream ampcode.com service.

ampcode.restrict-management-to-localhost

Default: false

When enabled, management routes (/api/auth, /api/user, /api/threads, etc.) only accept connections from localhost (127.0.0.1, ::1). This prevents:

• Drive-by browser attacks
• Remote access to management endpoints
• CORS-based attacks
• Header spoofing attacks (e.g., X-Forwarded-For: 127.0.0.1)

How It Works

This restriction uses the actual TCP connection address (RemoteAddr), not HTTP headers like X-Forwarded-For. This prevents header spoofing attacks but has important implications:

• ✅ Works for direct connections: Running CLIProxyAPI directly on your machine or server
• ⚠️ May not work behind reverse proxies: If deploying behind nginx, Cloudflare, or other proxies, the connection will appear to come from the proxy's IP, not localhost

Reverse Proxy Deployments

If you need to run CLIProxyAPI behind a reverse proxy (nginx, Caddy, Cloudflare Tunnel, etc.):

1. Keep the localhost restriction disabled (default):

   ampcode:
     restrict-management-to-localhost: false

2. Ensure API key auth is enabled (recommended):

   • Configure api-keys in config.yaml and have clients send the key
   • Combine with firewall/VPN/zero-trust controls to reduce exposure

3. Example nginx configuration (blocks external access to management routes):

   location /api/auth { deny all; }
   location /api/user { deny all; }
   location /api/threads { deny all; }
   location /api/internal { deny all; }

Note: ampcode.restrict-management-to-localhost is an extra hardening option; behind reverse proxies it is typically kept false.

Setup

1. Configure CLIProxyAPI

Create or edit config.yaml. You will need two types of API keys:

1. api-keys: For clients like Amp CLI to connect to your CLIProxyAPI instance.
2. ampcode.upstream-api-key: For CLIProxyAPI to connect to the ampcode.com backend. Get this from https://ampcode.com/settings.

port: 8317
auth-dir: "~/.cli-proxy-api"

# API keys for clients (e.g., Amp CLI) to use
api-keys:
  - "your-client-secret-key" # You can change this secret

# Amp integration
ampcode:
  upstream-url: "https://ampcode.com"
  # Your personal API key from ampcode.com
  upstream-api-key: "paste-your-ampcode-api-key-here"
  restrict-management-to-localhost: false

# Other standard settings...
debug: false
logging-to-file: true

2. Authenticate with Providers

Run OAuth login for the providers you want to use:

Google Account (Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 3 Pro Preview):

./cli-proxy-api --login

ChatGPT Plus/Pro (GPT-5, GPT-5 Codex):

./cli-proxy-api --codex-login

Claude Pro/Max (Claude Sonnet 4.5, Opus 4.1):

./cli-proxy-api --claude-login

Tokens are saved to:

• Gemini: ~/.cli-proxy-api/gemini-<email>.json
• OpenAI Codex: ~/.cli-proxy-api/codex-<email>.json
• Claude: ~/.cli-proxy-api/claude-<email>.json

3. Start the Proxy

./cli-proxy-api --config config.yaml

4. Configure Amp CLI

Option A: Settings File

Edit ~/.config/amp/settings.json:

{
  "amp.url": "http://localhost:8317",
  "amp.apiKey": "your-client-secret-key"
}

Option B: Environment Variable

export AMP_URL=http://localhost:8317
export AMP_API_KEY=your-client-secret-key

With this configuration, the amp login command is no longer necessary.

5. Use Amp

You are now ready to use Amp. All requests will be routed through your proxy.

amp "Write a hello world program in Python"

6. (Optional) Configure Amp IDE Extension

The proxy also works with Amp IDE extensions for VS Code, Cursor, Windsurf, etc.

1. Open Amp extension settings in your IDE.
2. Set Amp URL to http://localhost:8317.
3. Set Amp API Key to the key you configured (e.g., your-client-secret-key).
4. Start using Amp in your IDE. Both CLI and IDE can use the proxy simultaneously.

Usage

Supported Routes

Provider Aliases (Always Available)

These routes work even without ampcode.upstream-url configured:

• /api/provider/openai/v1/chat/completions
• /api/provider/openai/v1/responses
• /api/provider/anthropic/v1/messages
• /api/provider/google/v1beta/models/:action

Amp CLI calls these routes with your OAuth-authenticated models configured in CLIProxyAPI.

Management Routes (Require ampcode.upstream-url)

These routes are proxied to ampcode.com:

• /api/auth - Authentication
• /api/user - User profile
• /api/meta - Metadata
• /api/threads - Conversation threads
• /api/telemetry - Usage telemetry
• /api/internal - Internal APIs

Security: Requires an API key; ampcode.restrict-management-to-localhost is optional (default: false).

Model Fallback Behavior

When Amp requests a model:

1. Check local configuration: Does CLIProxyAPI have OAuth tokens for this model's provider?
2. If YES: Route to local handler (use your OAuth subscription)
3. If NO: Forward to ampcode.com (use Amp's default routing)

This enables seamless mixed usage:

• Models you've configured (Gemini, ChatGPT, Claude) → Your OAuth subscriptions
• Models you haven't configured → Amp's default providers

Example API Calls

Chat completion with local OAuth:

curl http://localhost:8317/api/provider/openai/v1/chat/completions \
  -H "Authorization: Bearer <your-cli-proxy-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Management endpoint (requires API key):

curl http://localhost:8317/api/user \
  -H "Authorization: Bearer <your-cli-proxy-api-key>"

Troubleshooting

Common Issues

Symptom	Likely Cause	Fix
404 on /api/provider/...	Incorrect route path	Ensure exact path: /api/provider/{provider}/v1...
401 on /api/user	Missing/invalid API key	Configure api-keys and send Authorization: Bearer <key> or X-Api-Key: <key>
403 on /api/user	Localhost restriction enabled and request is remote	Run from the same machine or set ampcode.restrict-management-to-localhost to false
401/403 from provider	Missing/expired OAuth	Re-run --codex-login or --claude-login
Amp gzip errors	Response decompression issue	Update to latest build; auto-decompression should handle this
Models not using proxy	Wrong Amp URL	Verify amp.url setting or AMP_URL environment variable
CORS errors	Protected management endpoint	Use CLI/terminal, not browser

Diagnostics

Check proxy logs:

# If logging-to-file: true
tail -f logs/requests.log

# If running in tmux
tmux attach-session -t proxy

Enable debug mode (temporarily):

debug: true

Test basic connectivity:

# Check if proxy is running
curl http://localhost:8317/v1/models

# Check Amp-specific route
curl http://localhost:8317/api/provider/openai/v1/models

Verify Amp configuration:

# Check if Amp is using proxy
amp config get amp.url

# Or check environment
echo $AMP_URL

Security Checklist

• ✅ Configure and protect api-keys (management routes require an API key)
• ✅ Enable ampcode.restrict-management-to-localhost: true for extra hardening when possible (default: false)
• ✅ Don't expose proxy publicly (bind to localhost or use firewall/VPN)
• ✅ Securely store your ampcode.upstream-api-key in the config file.
• ✅ Rotate OAuth tokens periodically by re-running login commands
• ✅ Store config and auth-dir on encrypted disk if handling sensitive data
• ✅ Keep proxy binary up to date for security fixes

Additional Resources

• Amp CLI Official Manual