vekil

README

vekil

One local endpoint for Anthropic, Gemini, and OpenAI clients — backed by the provider of your choice.

---

Vekil is a Go reverse proxy that exposes Anthropic, Gemini, and OpenAI-compatible APIs behind one local endpoint. Run it in zero-config mode against GitHub Copilot, or route selected models to providers like Azure OpenAI, OpenAI Codex, and generic OpenAI-compatible or Anthropic-compatible upstreams. The client-facing API surface stays the same while model ownership is configured behind the proxy.

Why Vekil?

Use your GitHub Copilot subscription with Claude Code, point the Codex CLI at Azure OpenAI, or send Gemini-CLI traffic through any OpenAI-compatible upstream — all without touching client config. Swap providers behind the proxy; your tools never notice.

Features

• Anthropic Messages API — drop-in compatible with Claude clients
• Gemini API — Generate Content, Stream Generate Content, and Count Tokens
• OpenAI Chat Completions and Responses APIs, including optional Codex websocket bridging
• Multi-provider routing across GitHub Copilot, Azure OpenAI, OpenAI Codex, and generic compatible providers
• Optional tool optimizers for opt-in shell command rewrites and tool-output reduction across supported API surfaces; see Tool Optimizers
• Codex compatibility shims for compaction and memory summarization
• Streaming, tool use, parallel tool calls, compressed request bodies, and auth/token caching

Quick Start

Grab a binary from GitHub Releases, or run the container from GHCR:

docker run -p 1337:1337 \
  -v ~/.config/vekil:/home/nonroot/.config/vekil \
  ghcr.io/sozercan/vekil:latest

On Apple Silicon Macs, install the native tray app via Homebrew:

brew install --cask sozercan/repo/vekil

The app is not signed. Clear quarantine with xattr -cr /Applications/Vekil.app. Manual vekil-macos-arm64.zip downloads are also on Releases. See Tray App (macOS/Linux).

For explicit provider routing, start the proxy with --providers-config /path/to/providers.{json,yaml}.

First-run auth depends on your providers:

• Copilot — vekil login uses Vekil-managed GitHub device-code sign-in; first proxy startup starts the same flow when needed. To use your current GitHub CLI account instead, opt in with vekil login --github-cli (or --gh). vekil logout clears cached auth and disables future silent gh reuse until you opt in again. COPILOT_GITHUB_TOKEN remains the explicit non-interactive override.
• Azure OpenAI and generic hosted providers — use api_key or api_key_env in your provider config.
• OpenAI Codex — requires codex login so ~/.codex/auth.json exists. In Docker, mount your Codex home into CODEX_HOME (default /home/nonroot/.codex).
• Local generic providers — use auth_type: none.

For full setup details, see Getting Started, Configuration, and Provider Routing.

Docs

Documentation lives under docs/; start with these:

Getting Started	Install, run, first auth
Configuration	Config map and generic flags
Provider Routing	Provider auth and model ownership
Provider API Keys	Where to get provider keys
Tool Optimizers	Shell rewrite/output reduction
Responses WebSocket	Websocket bridge tuning
Client Examples	Copy-paste snippets per client
API Reference	Endpoint behavior and compatibility
Architecture	Package layout and design notes
Tray App	macOS/Linux menubar usage
Development	Build, test, benchmarks, CI

Client Examples

Use any public model ID exposed by /v1/models — your client config is the same regardless of which provider owns the model upstream.

Claude Code

env ANTHROPIC_BASE_URL=http://localhost:1337 \
  ANTHROPIC_API_KEY=dummy \
  claude --model claude-sonnet-4 --print --output-format text "Reply with exactly PROXY_OK"

OpenAI Codex CLI

env OPENAI_API_KEY=dummy \
  OPENAI_BASE_URL=http://localhost:1337/v1 \
  codex exec --skip-git-repo-check -m gpt-5.5 "Reply with exactly PROXY_OK"

Gemini CLI

env GEMINI_API_KEY=dummy \
  GOOGLE_GEMINI_BASE_URL=http://localhost:1337 \
  GOOGLE_GENAI_API_VERSION=v1beta \
  GEMINI_CLI_NO_RELAUNCH=true \
  gemini -m gemini-2.5-pro -p "Reply with exactly PROXY_OK" -o json