Discord · API reference · Configuration · Custom quota checkers · Installation · Testing

Plexus sits in front of your LLM providers so clients can use one consistent API while you choose how requests are translated, routed, observed, and recovered. It supports OpenAI, Anthropic, Gemini, OpenAI-compatible providers, OAuth-backed subscriptions, and streamable HTTP MCP servers.

Why Plexus

• Keep client code stable. Accept OpenAI Chat Completions and Responses, Anthropic Messages, Gemini native requests, embeddings, audio, images, streaming, and tool use.
• Route on your terms. Map aliases to one or more targets with random, in_order, cost, performance, latency, usage, quota, or e2e_performance selection.
• Operate with evidence. Inspect request logs, tokens, cost, latency, live throughput, provider health, and per-key quotas from the dashboard.
• Stay resilient. Apply exponential cooldowns, fail over failed providers, detect stalled streams, and use vision fallthrough for non-vision targets.

Quick start

ADMIN_KEY is required for the dashboard and management API. DATABASE_URL is optional and defaults to SQLite at ./data/plexus.db; use a PostgreSQL connection string for production.

Run with Docker

docker run -p 4000:4000 \
  -v plexus-data:/app/data \
  -e ADMIN_KEY="your-admin-password" \
  -e ENCRYPTION_KEY="your-generated-hex-key" \
  ghcr.io/mcowger/plexus:latest

Or use a standalone binary

Download a pre-built binary from GitHub Releases:

# macOS Apple Silicon
curl -L https://github.com/mcowger/plexus/releases/latest/download/plexus-macos -o plexus
chmod +x plexus
ADMIN_KEY="your-admin-password" ./plexus
Linux x64
curl -L https://github.com/mcowger/plexus/releases/latest/download/plexus-linux -o plexus
chmod +x plexus
ADMIN_KEY="your-admin-password" ./plexus

# Windows x64
Invoke-WebRequest -Uri "https://github.com/mcowger/plexus/releases/latest/download/plexus.exe" -OutFile "plexus.exe"
$env:ADMIN_KEY = "your-admin-password"
$env:DATABASE_URL = "sqlite://./data/plexus.db"
.\plexus.exe

The binary is self-contained; database migrations and the web dashboard are embedded. See Installation for Docker Compose, Windows troubleshooting, source builds, and environment variables.

Send a request

Open the dashboard at http://localhost:4000, then create/configure an API key and model alias. Send a request:

curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-plexus-my-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "fast", "messages": [{"role": "user", "content": "Hello!"}]}'

OAuth providers are configured in the Admin UI. See Configuration: OAuth providers.

See the control plane

The dashboard is the operating view: configure providers and aliases, investigate every request, and watch usage and quota health.

| Dashboard | Providers | | --- | --- | | !Dashboard showing request volume, tokens, cost, and recent activity | !Providers view showing provider status, quota indicators, and controls | | Request logs | Model aliases | | !Request logs with model, provider, tokens, cost, latency, and live throughput | !Model aliases with targets, selectors, and routing priorities |

Built for the edges of provider APIs

Protocol translation handles OpenAI, Anthropic, Gemini, and compatible formats in both directions, including streaming and tool use. MCP proxying isolates sessions for streamable HTTP MCP servers. Encryption at rest protects API keys, OAuth tokens, provider secrets, and MCP headers with AES-256-GCM when ENCRYPTION_KEY is set. See Configuration for the full operating model.

Admin CLI

Pass a subcommand as the first argument to the binary or bun run src/index.ts:

• rekey decrypts sensitive fields with the current ENCRYPTION_KEY and re-encrypts them with NEW_ENCRYPTION_KEY.

ENCRYPTION_KEY="<current-key>" NEW_ENCRYPTION_KEY="<new-key>" ./plexus rekey

Development

bun install
bun run dev
bun run test

The dev port is derived from the worktree directory name. Use mise exec -- bun run dev when mise is not activated in your shell. For a background stack, use bun run dev:agent --detach and stop it with bun run dev:stop (prefix both with mise exec -- when needed). FRP exposure is optional: when frpc, FRPC_SERVER_ADDR, and FRPC_AUTH_TOKEN are available, the dev server creates a worktree-specific tunnel and tears it down with the server.

bun test is intentionally blocked; use bun run test. See Testing.

License

MIT License — see LICENSE.