Client Setup Guides

Getting Started

Get Corveil running in under 2 minutes. No Docker, no database, no Kubernetes.

1. Install

curl -sSL https://corveil.com/install.sh | sh

The installer automatically verifies the download against published SHA-256 checksums. Or download directly from GitHub Releases (macOS, Linux, Windows — ARM64 and AMD64) and verify manually.

2. Start Corveil

corveil --dev --openrouter-api-key sk-or-v1-...

That's it. Corveil starts on localhost:8000 with:

• SQLite database — created automatically, zero config
• Dev login enabled — no SSO or JWT setup needed
• Full dashboard — at http://localhost:8000

You can also use --anthropic-api-key for direct Anthropic access, or any other provider flag. Run corveil --help to see all options.

3. Connect an AI Tool

Create an API key in the dashboard, then point your AI tool at Corveil:

export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_API_KEY="sk-citadel-your-key-from-dashboard"

See the client setup guides below for tool-specific configuration.

Overview

Corveil supports two authentication modes for connecting AI tools:

• Direct Mode — Your Corveil virtual API key (sk-citadel-...) is used as the tool's API key. Corveil authenticates the request and forwards it upstream using its own provider credentials. This is the simplest setup.
• Passthrough Mode — Your own provider credentials (API key or OAuth token) flow through to the upstream provider. A separate x-citadel-api-key header authenticates with Corveil for tracking and guardrails. This requires custom header support in the client tool.

Compatibility Matrix

Why the difference? Passthrough mode requires the client to send a custom x-citadel-api-key header. Only Claude Code (via ANTHROPIC_CUSTOM_HEADERS) and OpenClaw (via custom headers config) support this. Tools that use the OpenAI-compatible API (Cursor, Codex CLI, OpenCode) only support Direct mode.

aichat

aichat is a powerful AI chat CLI that supports multiple providers via its OpenAI-compatible client configuration.

Prerequisites

• A running Corveil instance (see deployment options)
• A Corveil virtual API key (sk-citadel-...)
• aichat installed (brew install aichat or cargo install aichat)

Mode

Direct mode only. aichat uses the OpenAI-compatible client type, which sends your Corveil key as the standard API key.

1. Configure aichat

Open your aichat config file. Run aichat --info to find its location, then add a Corveil client:

clients:
- type: openai-compatible
  name: corveil
  api_base: https://your-corveil-host/v1    # must include /v1
  api_key: sk-citadel-your-key-here
  models:
  - name: or-claude-haiku-4.5
  - name: or-gpt-5.1

Replace your-corveil-host with your Corveil URL and sk-citadel-your-key-here with your virtual API key. List any models your key has access to — check GET /v1/models for the full list.

2. Start chatting

# One-shot query
aichat -m corveil:or-claude-haiku-4.5 "Explain zero-trust architecture"

# Interactive session
aichat -m corveil:or-claude-haiku-4.5

3. Verify connection

If aichat responds, requests are flowing through Corveil. Confirm by checking the Corveil dashboard or logs for the incoming request.

Troubleshooting

• 401 Unauthorized: Verify your api_key matches a valid Corveil virtual API key
• Connection refused: Ensure your Corveil instance is running and the api_base URL is reachable
• Model not found: Check that the model names match models available through your Corveil instance (GET /v1/models)
• Missing /v1 in URL: The api_base must include the /v1 path suffix

Claude Code

Claude Code is Anthropic's official CLI for Claude. It natively supports custom base URLs and headers, making it one of the most flexible tools for Corveil integration.

Prerequisites

• A running Corveil instance (see deployment options)
• A Corveil virtual API key (sk-citadel-...)
• Claude Code installed

Mode

Direct and Passthrough modes supported. Claude Code supports both ANTHROPIC_API_KEY override (Direct) and ANTHROPIC_CUSTOM_HEADERS (Passthrough).

Option A: Direct Mode

Your ANTHROPIC_API_KEY is a Corveil virtual key. Corveil authenticates the request and forwards it upstream using its own provider credentials.

export ANTHROPIC_BASE_URL="https://your-corveil-host"
export ANTHROPIC_API_KEY="sk-citadel-your-key-here"

Or configure via settings.json (project .claude/settings.json or global ~/.claude/settings.json):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-corveil-host",
    "ANTHROPIC_API_KEY": "sk-citadel-your-key-here"
  }
}

Option B: Passthrough Mode

Your own Anthropic API key or OAuth token is sent directly to Anthropic. A separate x-citadel-api-key header authenticates with Corveil for tracking and guardrails.

export ANTHROPIC_BASE_URL="https://your-corveil-host"
export ANTHROPIC_CUSTOM_HEADERS="x-citadel-api-key: sk-citadel-your-key-here"

Or configure via settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-corveil-host",
    "ANTHROPIC_CUSTOM_HEADERS": "x-citadel-api-key: sk-citadel-your-key-here"
  }
}

See the Claude Code settings documentation for details on project vs. global settings.

Launch and Verify

Start Claude Code as usual — it will automatically route all requests through Corveil:

claude

Ask a simple question. If it responds, requests are flowing through Corveil. Confirm in the dashboard or logs:

corveil logs --tail 5

How it works

• Routing: Claude Code sends all Anthropic API requests to your Corveil host
• Direct mode (Option A): ANTHROPIC_API_KEY is sent as the standard x-api-key header. Corveil uses it for auth, spend tracking, and policy enforcement, then forwards the request upstream using its own provider credentials
• Passthrough mode (Option B): x-citadel-api-key (via ANTHROPIC_CUSTOM_HEADERS) authenticates with Corveil for tracking and guardrails. The user's own OAuth token or API key flows through the Authorization header to Anthropic
• Full visibility: In both modes, every request and response is logged, guardrails are enforced, and costs are tracked — all transparent to the Claude Code user

Troubleshooting

• 401 Unauthorized (Direct mode): Verify your ANTHROPIC_API_KEY matches a valid Corveil virtual API key
• 401 Unauthorized (Passthrough mode): Verify your x-citadel-api-key header value is a valid Corveil virtual API key, and that your Anthropic credentials are valid
• Connection refused: Ensure your Corveil instance is running and the ANTHROPIC_BASE_URL is reachable
• Environment not picked up: Reload your shell after adding exports, or set them in the same terminal session. If using settings.json, ensure valid JSON in the correct location
• Custom headers not sent: Verify ANTHROPIC_CUSTOM_HEADERS uses the format header-name: value (colon-space separated)
• Model not available: Ensure your Corveil instance has the requested Anthropic models configured in its provider settings

OpenClaw

OpenClaw is an AI gateway client that supports custom provider routing with headers, making it ideal for Corveil's passthrough mode.

Prerequisites

• A running Corveil instance (see deployment options)
• A Corveil virtual API key (sk-citadel-...)
• OpenClaw installed and running (openclaw gateway run or the Mac app)
• An existing Anthropic API key or OAuth session configured in OpenClaw

Mode

Passthrough mode only. OpenClaw forwards your existing Anthropic credentials upstream. The x-citadel-api-key header authenticates with Corveil for tracking and guardrails.

1. Configure the Anthropic provider

Tell OpenClaw to route Anthropic requests through Corveil:

openclaw config set models.providers.anthropic '{
  "baseUrl": "https://your-corveil-host",
  "api": "anthropic-messages",
  "headers": {
    "x-citadel-api-key": "sk-citadel-your-key-here"
  },
  "models": [
    {
      "id": "claude-sonnet-4-6",
      "name": "Claude Sonnet 4.6",
      "reasoning": true,
      "input": ["text", "image"],
      "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
      "contextWindow": 200000,
      "maxTokens": 16384
    }
  ]
}'

Replace your-corveil-host with your Corveil URL and sk-citadel-your-key-here with your virtual API key. Setting costs to 0 is recommended since Corveil tracks spend on its side.

2. Restart the gateway

# If using the Mac app, restart from the menu bar
# Otherwise:
openclaw gateway restart

3. Verify the connection

# Check provider status
openclaw channels status --probe

# Send a test message
openclaw message send "Hello from OpenClaw via Corveil"

How passthrough mode works

• Routing: OpenClaw sends requests to your Corveil host instead of directly to api.anthropic.com
• Corveil auth: The x-citadel-api-key header authenticates the request with Corveil for spend tracking and policy enforcement
• Upstream auth: Your existing Anthropic credentials are forwarded to the upstream provider automatically
• Full visibility: Corveil logs every request/response, enforces guardrails, and tracks costs

Troubleshooting

• 401 Unauthorized from Corveil: Verify your x-citadel-api-key is valid and has not expired
• 401 from upstream provider: Check that your Anthropic credentials are still configured in OpenClaw (openclaw config get models.providers.anthropic)
• Connection refused: Ensure your Corveil instance is running and the baseUrl is reachable
• Model not found: The model IDs in your config must match models available through your Corveil instance

Cursor IDE

Cursor is an AI-powered code editor with built-in support for custom OpenAI-compatible endpoints.

Prerequisites

• A running Corveil instance (see deployment options)
• A Corveil virtual API key (sk-citadel-...)
• Cursor IDE installed

Mode

Direct mode only. Cursor uses the OpenAI-compatible API and does not support custom headers for passthrough authentication.

1. Open Model Settings

In Cursor, go to Settings > Models (or press Cmd+Shift+P / Ctrl+Shift+P and search for "Models").

2. Configure the OpenAI endpoint

1. Set "Override OpenAI Base URL" to:
   https://your-corveil-host/v1
2. Set "OpenAI API Key" to:
   sk-citadel-your-key-here
3. Click "+ Add Model" to add models available through your Corveil instance (e.g., or-claude-haiku-4.5, or-gpt-5.1)

3. Verify connection

Open a file in Cursor and use the AI features (inline edit, chat, or Cmd+K). If Cursor responds with AI suggestions, requests are flowing through Corveil.

Troubleshooting

• 401 Unauthorized: Verify the "OpenAI API Key" field contains a valid Corveil virtual API key
• Connection refused: Ensure the "Override OpenAI Base URL" is correct and reachable, including the /v1 suffix
• No models available: You must manually add model names via "+ Add Model" — they must match models configured in your Corveil instance
• Falling back to Cursor's models: Make sure the base URL override is saved and Cursor is not using its built-in API keys

OpenCode

OpenCode is an open-source AI coding assistant that runs in your terminal. It supports the OpenAI-compatible API via environment variables.

Prerequisites

• A running Corveil instance (see deployment options)
• A Corveil virtual API key (sk-citadel-...)
• OpenCode installed

Mode

Direct mode only. OpenCode uses the standard OpenAI environment variables and does not support custom headers.

1. Set environment variables

export OPENAI_BASE_URL="https://your-corveil-host/v1"
export OPENAI_API_KEY="sk-citadel-your-key-here"

Add these to your shell profile (~/.zshrc, ~/.bashrc, etc.) for persistence.

2. Launch OpenCode

opencode

3. Verify connection

Ask OpenCode a question. If it responds, requests are flowing through Corveil. Confirm in the Corveil dashboard or logs.

Troubleshooting

• 401 Unauthorized: Verify OPENAI_API_KEY is a valid Corveil virtual API key
• Connection refused: Ensure OPENAI_BASE_URL is correct and reachable, including the /v1 suffix
• Environment not picked up: Reload your shell (source ~/.zshrc) or set the variables in the same terminal session
• Model not found: Ensure the model you're requesting is available through your Corveil instance

Codex CLI

Codex CLI is OpenAI's open-source coding agent that runs in your terminal. It supports custom base URLs via environment variables.

Prerequisites

• A running Corveil instance (see deployment options)
• A Corveil virtual API key (sk-citadel-...)
• Codex CLI installed (npm install -g @openai/codex)

Mode

Direct mode only. Codex CLI uses the standard OpenAI environment variables and does not support custom headers.

1. Set environment variables

export OPENAI_BASE_URL="https://your-corveil-host/v1"
export OPENAI_API_KEY="sk-citadel-your-key-here"

Add these to your shell profile for persistence.

2. Launch Codex

codex

3. Verify connection

Run a coding task. If Codex responds with suggestions, requests are flowing through Corveil.

Custom TLS Certificates

For deployments with custom TLS certificates (common in GovCloud environments), Codex CLI supports a dedicated environment variable:

# Point to your custom CA certificate
export CODEX_CA_CERTIFICATE="/path/to/your/ca-cert.pem"

Troubleshooting

• 401 Unauthorized: Verify OPENAI_API_KEY is a valid Corveil virtual API key
• Connection refused: Ensure OPENAI_BASE_URL is correct and reachable, including the /v1 suffix
• TLS errors: If using a custom CA, set CODEX_CA_CERTIFICATE to your CA certificate path
• Model not found: Ensure the requested model is available through your Corveil instance

Gemini CLI Beta

Gemini CLI is Google's command-line interface for Gemini models. Environment variable support for custom endpoints is still evolving upstream.

Prerequisites

• A running Corveil instance (see deployment options)
• A Corveil virtual API key (sk-citadel-...)
• Gemini CLI installed (npm install -g @anthropic-ai/gemini-cli or see project README)

Mode

Direct mode only (Beta). Gemini CLI can be pointed at a custom base URL via environment variables. This is experimental — env var support is still evolving upstream.

1. Set environment variables

export GEMINI_API_KEY="sk-citadel-your-key-here"

Add these to your shell profile for persistence.

2. Launch Gemini CLI

gemini

3. Verify connection

Ask a question. If Gemini CLI responds, requests are flowing through Corveil. Confirm in the dashboard or logs.

Troubleshooting

• Env vars not recognized: Gemini CLI's env var support is evolving. Check the project README for the latest configuration options
• 401 Unauthorized: Verify GEMINI_API_KEY is a valid Corveil virtual API key
• Connection refused: Ensure your Corveil instance is running and reachable
• Model not found: Ensure Gemini models are configured in your Corveil instance's provider settings