Client Setup Guides
Step-by-step instructions for connecting your AI tools to Corveil.
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:
- PostgreSQL via the included docker-compose — pgvector image, one command to start
- 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. Pick your tool from the selector below to see the exact configuration.
Authentication Modes
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 and works with every OpenAI-compatible tool.
- 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 — today, Claude Code (ANTHROPIC_CUSTOM_HEADERS) and OpenClaw (custom headers config) are the main supported tools.
Every guide below identifies which mode(s) it supports.
Pick your tool
Select a client below to see install and configuration steps for connecting it to Corveil.
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
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
FAQ
Frequently Asked Questions
How do I install Corveil?
Run "curl -sSL https://corveil.com/install.sh | sh" to install the binary. The installer verifies the download against SHA-256 checksums. Alternatively, download directly from GitHub Releases for macOS, Linux, or Windows (ARM64 and AMD64).
Does Corveil work with Claude Code?
Yes. Set ANTHROPIC_BASE_URL to your Corveil instance URL and ANTHROPIC_API_KEY to your Corveil API key. Claude Code will route all requests through Corveil. Passthrough mode is also supported for Claude Code Max subscribers who want logging and guardrails while using their own subscription.
What AI tools does Corveil support?
Corveil works with any tool that supports OpenAI-compatible or Anthropic-compatible APIs. Tested clients include aichat, Claude Code, OpenClaw, Cursor IDE, OpenCode, Codex CLI, and Gemini CLI. Setup guides are available for each.
Do I need Kubernetes to run Corveil?
No. Corveil runs as a single Go binary against PostgreSQL — no Lua runtime, no plugin DSL, no service mesh. The included pgvector docker-compose covers local dev; production deploys via Helm chart, ECS Fargate, or your container platform of choice.
How do I create an API key?
Start Corveil with --dev mode enabled, open the dashboard at localhost:8000, and create an API key from the Keys page. The key will have the format sk-citadel-xxx. Use this key in your AI tool's configuration to authenticate requests through Corveil.
Can I use multiple LLM providers at the same time?
Yes. Configure multiple provider API keys (OpenRouter, Anthropic, Vertex AI, Bedrock) and Corveil routes requests to the appropriate provider based on the model name. Switch models with a configuration change — no code changes required in your AI tools.