---
## ✨ Features
| Feature | Description |
|---------|-------------|
| 🔐 **User-level access control** | Per-user API keys with group-based model ACLs, anonymous user support |
| 🔄 **Credential rotation & failover** | Multiple upstream keys with automatic rotation and retry |
| 📊 **Operational visibility** | Request logging, persistent stats, real-time SSE log stream, Web Console |
| 📈 **Prometheus metrics** | `/metrics` endpoint with Bearer auth, request counters, latency histograms, circuit breaker state |
| 🔭 **OpenTelemetry tracing** | OTLP gRPC export (feature-gated), W3C Trace Context propagation, 42 `#[instrument]` spans |
| 📋 **Audit logging** | Config change audit trail (who/what/when) in SQLite/PostgreSQL, fire-and-forget writes |
| 🌐 **Protocol translation** | OpenAI ↔ Anthropic ↔ Gemini ↔ AWS Bedrock ↔ DashScope ↔ Passthrough, transparent bridging |
| 📝 **Script transforms** | Custom request/response manipulation via JavaScript scripts ([Scripting Guide](docs/scripting.md)) |
| 🚀 **Deployment-friendly** | TOML config + env vars, Docker-ready, single binary (zero external deps for single-instance; PostgreSQL/Redis optional for multi-instance) |
| 🛡️ **Security hardened** | bcrypt password hashing, IP ban protection, API key masking, security headers, per-IP rate limiting |
| ⚡ **High performance** | Rust + Tokio async runtime, no GC pauses |
| ⚖️ **Model-level load balancer** | Weighted round-robin, sticky sessions, failure-based degradation, 429 rate-limit failover across upstreams |
| 🗄️ **Distributed state** | Redis-backed sessions, rate limiting, log broadcast, and IP ban for multi-instance deployments |
| ☸️ **Kubernetes-ready** | Liveness/readiness probes, graceful shutdown with pre-stop drain, configurable timeouts |
| 🛠️ **MCP Gateway** | Built-in MCP (Model Context Protocol) proxy, aggregating external tool servers with ACL, context budgeting, and BM25 tool search |
## 🌍 Supported Protocols
| Protocol | Executor | Status |
|----------|----------|--------|
| OpenAI Chat Completions | `openai` | ✅ Production |
| OpenAI Response | `openai_response` | ✅ Production |
| OpenAI Images | `openai_images` | ✅ Production |
| OpenAI Embeddings | `openai_embeddings` | ✅ Production |
| OpenAI Audio | `openai_audio` | ✅ Production |
| Anthropic Messages | `anthropic` | ✅ Production |
| Gemini Generative Language | `google` | ✅ Production |
| AWS Bedrock Converse | `aws_converse` | ✅ Production |
| AWS Bedrock InvokeModel | `aws_invoke` | ✅ Production |
| Alibaba DashScope | `dashscope` | ✅ Production |
| Passthrough (proxy) | `passthrough` | ✅ Production |
Endpoints outside this scope return `501 Not Implemented` instead of placeholder data.
> [!NOTE]
> Protoflux uses API Key authentication exclusively. **OAuth is not supported** — subscription services like OpenAI and Anthropic typically prohibit using accounts for API access, violating vendor terms.
## 🚀 Quick Start
### Prerequisites
- Rust 1.80+ (`rustup default stable`)
- Your LLM API keys
### 1. Copy config
```bash
cp server.example.toml server.toml
# Edit server.toml for infrastructure settings (server, logging, cors, etc.)
# Business config (users, upstreams, models) is managed via Console after startup
```
### 2. Validate config
```bash
cargo run -- --config server.toml config-validate
```
### 3. Start the server
```bash
cargo run -- --config server.toml serve
```
### 4. Health check
```bash
cargo run -- health-check --url http://localhost:7890
```
> 💡 Config files support `${ENV_VAR}` expansion. Bare `$VAR` is intentionally not expanded to avoid conflicts with bcrypt hashes.
### 🐳 Docker Quick Start
Protoflux supports two storage modes. **SQLite** for single-instance deployments (default) and **PostgreSQL** for multi-instance container deployments with shared state.
#### SQLite Mode (single instance)
Config and stats are stored in local files. Business config is persisted in the SQLite database. Ideal for development, single-node deployments, or when you don't need multi-instance coordination.
```bash
docker pull ghcr.io/taichulab/protoflux:latest
docker run -d \
--name protoflux \
-p 7890:7890 \
-v $(pwd)/server.toml:/etc/protoflux/server.toml:ro \
-v protoflux-data:/var/lib/protoflux \
ghcr.io/taichulab/protoflux:latest
```
> SQLite mode requires mounting a data volume (`/var/lib/protoflux`) to persist the stats and config database across restarts. Configure endpoints and view stats via the Web Console at `http://localhost:7890/console`.
#### PostgreSQL Mode (multi-instance)
Config, stats, and business data are stored in PostgreSQL. Multiple gateway instances can share the same database for horizontal scaling and centralized config management via Console.
```bash
# Start PostgreSQL
docker run -d \
--name protoflux-pg \
-e POSTGRES_USER=protoflux \
-e POSTGRES_PASSWORD=changeme \
-e POSTGRES_DB=protoflux \
-p 5432:5432 \
postgres:17-alpine
# Start Protoflux (connects to PG)
docker run -d \
--name protoflux \
-p 7890:7890 \
-e POSTGRES_URL="postgresql://protoflux:changeme@host.docker.internal:5432/protoflux" \
-v $(pwd)/server.toml:/etc/protoflux/server.toml:ro \
ghcr.io/taichulab/protoflux:latest
```
With the config TOML:
```toml
[server]
storage_mode = "postgresql"
postgres_url = "${POSTGRES_URL}"
```
> PostgreSQL auto-creates stats tables via refinery migrations. Business config (users, upstreams, models) is managed through the Console and persisted in the database. Both SQLite and PostgreSQL modes support Console-based endpoint configuration and statistics viewing.
## 🛠️ For Developers
### Build
```bash
# Debug build (fast compilation)
cargo build
# Release build (optimized binary, LTO enabled)
cargo build --release
# Build a specific crate
cargo build -p protoflux-core
cargo build -p protoflux-server
```
### Test
Tests use inline `#[cfg(test)]` blocks by default. Extract to `crates/