{
  "markdown": "<div align=\"center\">\n  <h1>⚡ Styx</h1>\n  <p><strong>The MCP-Native AI Gateway</strong></p>\n  <p>Route requests to any AI provider through one universal endpoint.<br/>\n  Self-hosted. Open source. BYOK.</p>\n\n  <!-- Badges -->\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" /></a>\n  <a href=\"https://github.com/timmx7/styx/stargazers\"><img src=\"https://img.shields.io/github/stars/timmx7/styx\" /></a>\n  <a href=\"https://github.com/timmx7/styx/issues\"><img src=\"https://img.shields.io/github/issues/timmx7/styx\" /></a>\n</div>\n\n---\n\n## What is Styx?\n\nStyx is an open-source AI gateway that sits between your app and AI providers. Send requests to OpenAI, Anthropic, Google, or Mistral — all through one OpenAI-compatible endpoint. Bring your own API keys, self-host on your infra, and get full visibility into every request.\n\n**The first AI gateway with native MCP (Model Context Protocol) support.**\n\n```python\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=\"your-styx-api-key\",\n    base_url=\"http://localhost:8080/v1\",  # ← Only change needed\n)\n\nresponse = client.chat.completions.create(\n    model=\"gpt-4o\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello from Styx\"}],\n)\n```\n\n## Features\n\n- 🔌 **MCP Native** — Built-in MCP server. Connect Claude Code or Cursor in one command\n- 🔀 **Universal Routing** — One OpenAI-compatible endpoint for all providers\n- 🤖 **styx:auto** — Intelligent model routing: use `\"model\": \"styx:auto\"` and let Styx pick the right model based on request complexity\n- 🔑 **BYOK** — Bring your own API keys, encrypted at rest (Fernet/AES)\n- 📊 **Dashboard** — Track requests, costs, latency per project and model\n- 🔄 **Fallbacks** — Auto-failover between providers with circuit breakers\n- 💰 **Billing** — Built-in subscription and credit-based billing (Stripe)\n- 🧠 **Semantic Cache** — Similar questions return cached responses instantly\n- ⚡ **Smart Routing** — ML classifier routes to the optimal model for each request\n- 🐳 **Self-Hosted** — Docker Compose, 5-minute setup\n- 🔒 **Secure** — HMAC key hashing, Fernet encryption, rate limiting, TLS\n\n## Prerequisites\n\n- **Docker Engine 24+** and Docker Compose v2\n- **At least one AI provider API key** (OpenAI, Anthropic, Google, or Mistral)\n- **Supabase account** ([free tier](https://supabase.com)) — only for production mode (not needed for dev mode)\n\n## Quick Start\n\n### Option A: Setup Wizard (recommended)\n\n```bash\ngit clone https://github.com/timmx7/styx.git\ncd styx\n./setup.sh                 # interactive wizard, generates .env\ndocker compose up -d --build   # first build: ~15-20 min; subsequent starts: ~60s\n```\n\nThe wizard lets you choose between:\n- **Dev mode** — No Supabase needed, no authentication, instant start\n- **Production mode** — Full Supabase auth, account creation, API keys\n\n### Option B: Manual Setup\n\n```bash\ngit clone https://github.com/timmx7/styx.git\ncd styx\ncp .env.example .env\n```\n\nEdit `.env` with:\n1. Set `SKIP_AUTH=true` for dev mode, or configure **Supabase** for production\n2. At least one **AI provider key** (e.g., `OPENAI_API_KEY`)\n\n```bash\ndocker compose up -d --build   # first build: ~15-20 min; subsequent starts: ~60s\n```\n\n### Access Points\n\n- **Dashboard:** http://localhost:3000\n- **API Gateway:** http://localhost:8080 (direct) or https://localhost/v1 (via nginx/TLS)\n- **Docs API:** https://localhost/api (via nginx)\n\n### Connect Claude Code\n\n```bash\nclaude mcp add styx -- npx styx-mcp\n```\n\n### Connect Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"styx\": {\n    \"command\": \"npx\",\n    \"args\": [\"styx-mcp\"],\n    \"env\": { \"STYX_API_KEY\": \"your-key\" }\n  }\n}\n```\n\n### Send your first request\n\n```bash\ncurl -X POST http://localhost:8080/v1/chat/completions \\\n  -H \"Authorization: Bearer YOUR_STYX_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"gpt-4o\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"Hello from Styx\"}]\n  }'\n```\n\n> **Dev mode:** skip the `Authorization` header — requests are accepted without an API key.\n\n### Use with any OpenAI SDK\n\n```typescript\n// Node.js / TypeScript\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  apiKey: \"your-styx-key\",\n  baseURL: \"http://localhost:8080/v1\",\n});\n```\n\n```python\n# Python\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=\"your-styx-key\",\n    base_url=\"http://localhost:8080/v1\",\n)\n```\n\n## Supported Providers\n\n| Provider | Models | Status |\n|----------|--------|--------|\n| OpenAI | gpt-4.1, gpt-4.1-mini, gpt-4o, gpt-4o-mini, o3, o4-mini | ✅ |\n| Anthropic | claude-sonnet-4, claude-3-5-sonnet, claude-3-5-haiku, claude-3-haiku | ✅ |\n| Google | gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.0-flash | ✅ |\n| Mistral | mistral-large, mistral-medium-3, mistral-small, codestral | ✅ |\n| Azure OpenAI | Same as OpenAI models, via Azure deployments | ✅ |\n\n> **Auto-routing:** Any model matching the provider prefixes above (`gpt-*`, `claude-*`, `gemini-*`, `mistral-*`, `o3*`, `o4*`) is routed automatically — even models released after your last config update.\n\n## Architecture\n\n```\n┌─────────┐     ┌──────────────┐     ┌───────────────┐\n│  Client  │────▶│  Go Router   │────▶│  AI Provider  │\n│  (app)   │◀────│  (port 8080) │◀────│  (OpenAI...)  │\n└─────────┘     └──────┬───────┘     └───────────────┘\n                       │\n                ┌──────▼───────┐\n                │ Python API   │\n                │ (port 8000)  │\n                │ Auth/Billing │\n                └──────┬───────┘\n                       │\n          ┌────────────┼────────────┐\n          │            │            │\n    ┌─────▼──┐  ┌──────▼──┐  ┌─────▼──┐\n    │Postgres│  │  Redis   │  │ Next.js│\n    │  (DB)  │  │ (cache)  │  │ (UI)   │\n    └────────┘  └─────────┘  └────────┘\n```\n\n**Request flow:**\n\n```\nClient request\n    │\n    ▼\nGo Router (:8080) ──▶ Cache check ──▶ HIT? Return instantly\n    │                                   MISS? Continue...\n    ▼\nBudget check ──▶ OVER LIMIT? Block + alert\n    │              OK? Continue...\n    ▼\nRoute to best provider (OpenAI / Anthropic / Google / Mistral)\n    │\n    ▼\nProvider error? ──▶ Automatic fallback (circuit breaker)\n    │\n    ▼\nResponse to client + log to ClickHouse + update Redis counters\n```\n\n## Project Structure\n\n```\nstyx/\n├── router/          # Go reverse proxy — the fast path (<10ms overhead)\n├── backend/         # Python FastAPI — auth, billing, business logic\n├── dashboard/       # Next.js + Tailwind — web dashboard\n├── classifier/      # ML request classifier (complexity scoring)\n├── cache-service/   # Semantic cache (Qdrant + sentence-transformers)\n├── sdk/             # Python & Node.js client SDKs\n├── packages/        # MCP server, gateway CLI\n├── infra/           # Docker, Helm, K8s, k6 load tests, Prometheus\n└── docker-compose.yml\n```\n\n## Comparison\n\n| Feature | Styx | OpenRouter | LiteLLM | Portkey |\n|---------|------|-----------|---------|---------|\n| MCP Native | ✅ | ❌ | ❌ | ❌ |\n| Self-Hosted | ✅ | ❌ | ✅ | ❌ |\n| Open Source | ✅ Apache 2.0 | ❌ | ✅ | ❌ |\n| Dashboard | ✅ Full | ❌ | Basic | ✅ |\n| BYOK | ✅ Encrypted | ❌ | ✅ | ✅ |\n| Semantic Cache | ✅ | ❌ | ❌ | ❌ |\n| Smart Routing | ✅ ML | ❌ | ❌ | ✅ |\n| Circuit Breaker | ✅ | ❌ | ✅ | ✅ |\n| One-Command Install | ✅ | N/A | ❌ | N/A |\n\n## Claude Code Plugin\n\nInstall the Styx plugin directly in Claude Code:\n\n```\n/plugin install styx@claude-plugin-directory\n```\n\nOr browse: `/plugin > Discover > styx`\n\nThis gives you `/styx:setup`, `/styx:status`, and the `@styx-ops` agent for managing your gateway from Claude Code.\n\n## MCP Connector\n\nStyx includes a native MCP server. Connect it to Claude, Cursor, or any MCP-compatible client.\n\n### Local (stdio — requires npx)\n\n**Claude Code:**\n```bash\nclaude mcp add styx -- npx styx-mcp\n```\n\n**Cursor:** Add to `.cursor/mcp.json`:\n```json\n{\n  \"styx\": {\n    \"command\": \"npx\",\n    \"args\": [\"styx-mcp\"],\n    \"env\": { \"STYX_API_KEY\": \"your-key\" }\n  }\n}\n```\n\n### Remote MCP Server\n\nConnect to a hosted Styx instance without local installation:\n\n**Claude.ai / Claude Desktop:**\nSettings > Connectors > Add custom connector > URL: `https://mcp.styxhq.com/mcp`\n\n**Claude Code:**\n```bash\nclaude mcp add --transport http styx https://mcp.styxhq.com/mcp\n```\n\nSee [docs/DEPLOY_MCP_REMOTE.md](docs/DEPLOY_MCP_REMOTE.md) for self-hosting the remote MCP server.\n\n## Examples\n\n### Check gateway health\n**Prompt:** \"Check if my AI gateway is healthy and which providers are connected\"\n→ Styx checks all provider connections, returns status and latency per provider, flags any issues.\n\n### Analyze spending\n**Prompt:** \"How much have I spent on AI APIs this month?\"\n→ Styx aggregates usage across providers, returns cost breakdown by model, shows cache savings.\n\n### Create a scoped API key\n**Prompt:** \"Create an API key for the marketing team limited to 1000 requests/day\"\n→ Styx generates a rate-limited key, returns the key and its configuration.\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE) for details.\n\n## Links\n\n- [Privacy Policy](privacy-policy.md)\n- [Security](SECURITY.md)\n- [Support](https://github.com/styx-hq/styx/issues)\n\n",
  "bytes": 9163,
  "sha": "be05ca6e45df3a7596607d07b8efd97f0c56f09ecd5f5db1781d3eed755d46a4",
  "repo_slug": "timmx7/styx",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_timmx7_styx_mcp_server_de196a60/readme"
}