rolter

A high-performance, open-source LiteLLM-proxy alternative in Rust —
an OpenAI/Anthropic-compatible AI gateway and load balancer.

rolter proxies commercial providers and load-balances self-hosted OpenAI-compatible fleets (e.g. 20–30 vLLM instances) with cache-aware routing, full RBAC, reload-free configuration, and cost/usage tracking.

Status: active development. The gateway, Postgres-backed control plane, reload-free configuration, cost controls, reliability primitives, and core provider surfaces are implemented; remaining work is tracked in ROADMAP.md, TODO.md, and GitHub issues.

• Fast — a Rust data plane (Axum/Hyper/Tower on Tokio) with lock-free config reads and minimal-copy streaming.
• Cache-aware load balancing — route prefix-heavy traffic to the vLLM replica most likely to have the KV cache warm.
• Drop-in — speak the OpenAI and Anthropic APIs your clients already use.
• Operable — virtual keys, budgets, rate limits, cost tracking, RBAC, and reload-free config changes from the UI.

Go from zero to a working AI gateway in under a minute. The built-in fake-llm model answers locally, so the first request needs no provider key or config.

# single image: gateway + dashboard, no compose or config file
docker pull ghcr.io/rolter-ai/rolter:latest
docker run --rm -p 4000:4000 -p 4001:4001 ghcr.io/rolter-ai/rolter:latest

# native binary (installed from a release, cargo, uv, or pip)
rolter easy-up

Open the dashboard at http://localhost:4001. For Postgres, Redis, and ClickHouse, use the full-stack option instead:

docker compose -f docker/docker-compose.yml up -d

The dashboard is ready at http://localhost:4001. Add real providers and routes there when running in database mode, or use the bundled rolter.toml as your file-backed bootstrap config.

curl -s http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-rolter-dev" \
  -H "Content-Type: application/json" \
  -d '{"model":"fake-llm","messages":[{"role":"user","content":"hello"}]}'

Install methods, the rolter CLI reference, and production configuration are in the documentation.

flowchart LR
  Client([OpenAI / Anthropic clients]) -->|/v1/*| GW["rolter-gateway<br/>(data plane)"]
  Admin([Dashboard]) --> CTL["rolter-control<br/>(control plane + UI host)"]
  GW -->|balanced + streamed| UP["Upstreams<br/>OpenAI · Anthropic · vLLM pool"]
  CTL -->|writes config| PG[("PostgreSQL")]
  CTL -->|publishes change events| RDS[("Redis")]
  RDS -->|hot-swap snapshot| GW
  GW -->|async batched logs| CH[("ClickHouse")]

rolter stands on the shoulders of great open-source projects and research. See our inspiration issues for detailed analysis of each project.

• LiteLLM — proxy feature breadth, provider coverage (100+), config/DB model split, virtual keys, budget controls, spend tracking
• Bifrost — high-performance Go gateway, weighted key selection (~10ns), multi-provider failover, plugin/middleware system, hierarchical budgets, semantic caching; published perf target (~11µs latency at 5k RPS)
• TensorZero — Rust LLMOps gateway, sub-1ms p99 latency target at 10k+ QPS, observability patterns, OTLP traces + Prometheus, rate limiting with granular scopes
• llm-d — cache-aware routing, prefix/KV-cache affinity, inference-phase scheduling, predicted-latency scheduling (40% TTFT/ITL reduction); highest-signal reference for rolter-balancer crate
• LLMGateway — cost tracking, analytics dashboard UX, performance analytics, provider key management, self-host story (Docker + Postgres + Redis)
• Archestra — dynamic model routing, MCP gateway, enterprise auth (OIDC, SAML, Okta, Entra), SSO + RBAC, tool-call safety guardrails

• vLLM — KV-cache-aware replica pooling and prefill/decode scheduling
• Axum — high-performance Rust web framework
• Tokio — async runtime foundation
• shadcn/ui — component library for the dashboard UI

• OpenAI and Anthropic — API compatibility targets and standards

• Quickstart and Installation — install methods and the unified rolter CLI (gateway / control / easy-up)
• Configuration, Deployment, and Observability guides
• Air-gapped install & operation — running fully offline behind an internal mirror
• Architecture overview — the full design and ADRs

• crates/rolter-core — config model, domain types, errors, telemetry
• crates/rolter-balancer — load-balancing strategies (incl. approximate cache-aware)
• crates/rolter-proxy — upstream forwarding, header injection, streaming
• crates/rolter-store — storage traits, postgres feature backend (source of truth), ClickHouse-backed request logs
• crates/rolter-auth — virtual keys, roles, access checks
• crates/rolter-gateway — data-plane binary
• crates/rolter-control — control-plane binary + static UI host
• crates/rolter — unified rolter launcher (gateway / control / easy-up)
• ui/ — Vite + React + shadcn/ui dashboard
• docs/, docs/user-docs/ — architecture/ADRs and the user documentation site
• crates/rolter-store/migrations/, clickhouse/ — database schemas

The library crates are internal. rolter-core, rolter-auth, rolter-balancer, rolter-proxy, rolter-store, rolter-gateway and rolter-control are published to crates.io only because cargo install rolter cannot resolve otherwise. They offer no stable Rust API: any public item may change or disappear in any release, including a patch release, and they share the product's version number rather than carrying one of their own. Build against rolter's HTTP surfaces — the gateway API, the control API, the config file — which do carry a compatibility promise. See Versioning & compatibility and ADR-0032.

What a major version guarantees, per surface — the OpenAI/Anthropic gateway API, the control API, config files, the database schema and the crates — is written down in Versioning & compatibility, with the reasoning in ADR-0032. Short version: /api/v1/* is additive and nothing is removed without two minor releases and 90 days of notice; /v1/* guarantees fidelity to the OpenAI and Anthropic dialects rather than a frozen schema; the Rust crates guarantee nothing.

cargo build --workspace
cargo nextest run --workspace   # tests via nextest (as CI does); + `cargo test --doc --workspace`
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings

Commits and PR titles follow Conventional Commits. See AGENTS.md and docs/dev-docs/development/contributing.md.

Apache-2.0 — see LICENSE.