Stravia

Local agent infrastructure — one endpoint for every AI client.

Unified model access, tools that run for you, and shared access control,

history, and usage — desktop app or single binary.

Releases · Changelog · 中文文档

Status: Stravia is pre-1.0 and under active development. Configuration and database compatibility may change before a stable release.

What is Stravia

Stravia is local, self-hostable agent infrastructure for developers who use AI coding clients or build agent-powered apps. Your clients keep the protocol they already speak — OpenAI, Anthropic, or Gemini — and simply point at Stravia. Stravia decides which upstream service should answer and translates between protocols when needed.

On top of model access, the platform runs tools itself: built-in web search and media understanding execute inside Stravia and hand results back to the model — through ordinary model requests or MCP, no client plugins required. Access control, request history, usage, and diagnostics all live in the same place.

Claude Code · Codex CLI · Gemini CLI · OpenCode · SDKs
                            │
                            ▼
              Stravia unified listener :23471
                ├─ OpenAI-compatible API
                ├─ Anthropic Messages API
                ├─ Gemini GenerateContent API
                ├─ MCP tools
                ├─ Platform tools and built-in agent execution
                ├─ Admin API
                └─ WebUI
                            │
                            ▼
 OpenAI · Anthropic · Google · Vertex AI · DeepSeek · Ollama · …

Agent behavior is defined and versioned by the platform — Stravia is not a user-defined agent or visual workflow builder.

Why Stravia

• Drop-in endpoint for AI coding clients — point Claude Code, Codex CLI, Gemini CLI, or OpenCode at 127.0.0.1:23471 and keep working. Each client keeps its own protocol; Stravia handles translation, routing, and failover.
• Tools that run for you — built-in web search (local search uses an installed Chrome/Chromium browser; the container includes Chromium) and image understanding execute inside Stravia and hand results back to the model. Expose them over MCP or add them automatically to compatible requests.
• Keys, spend, and request history in one place — give each app its own key with model access and RPM limits, see the usage providers actually report, watch every request live, and download a full debug bundle when something goes wrong.
• Local-first, one Rust core — a desktop app or a headless server binary; SQLite by default, PostgreSQL for teams; local or S3 file storage. No cloud dependency.

Quick Start

Desktop — download the Windows (NSIS) or Linux (AppImage) installer from GitHub Releases and open it. The full platform runs locally with an integrated management UI. macOS builds are not currently provided.

If startup fails, the desktop app provides diagnostics and recovery options; it does not automatically reset your database.

Server — one container:

docker run --rm \
  --publish 127.0.0.1:23471:23471 \
  --mount source=stravia-data,target=/data \
  ghcr.io/stravia-ai/straviaplatform:latest

Alternatively, download a platform archive from Releases (verify against SHA256SUMS).

Nix / NixOS (Linux Server only): Build this checkout with nix build .#stravia-server, or import nixosModules.default and enable services.stravia. See Nix deployment.

Upgrading an existing instance: Stop and back up the complete data directory and any external database first. The Route output-purpose migration makes all historical Routes nonexecutable until individually reconfigured, on both SQLite and PostgreSQL. See upgrade and recovery; rollback requires restoring the backup.

First run (both):

1. Open http://127.0.0.1:23471/setup and paste the one-time setup token printed to the console. Pick SQLite or PostgreSQL and create the administrator. PostgreSQL requires Redis configured before setup; see cache and Server configuration.
2. Add a provider — API key or OAuth channel (Codex, Claude subscription, Grok device flow, Devin). Stravia syncs the available model inventory.
3. Add a model — choose text or image output, then select matching upstream models; the Model ID is the route clients call.
4. Create an API key, then open Connect clients — Stravia generates a ready-to-apply provider patch for Claude Code, Codex CLI, Gemini CLI, or OpenCode; the desktop app can write the config for you.

Then call it through any supported protocol:

curl http://127.0.0.1:23471/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PROXY_KEY" \
  -d '{"model": "my-model", "messages": [{"role": "user", "content": "Hello"}]}'

Features

Unified model access

Cross-protocol tool calls, reasoning, and usage reporting are preserved; requests that need no changes pass through as-is.

Providers and model routing

OpenAI (incl. Codex OAuth) · Anthropic (API key; Claude Pro/Max subscription OAuth via the Claude Code plugin — using a subscription outside Claude Code may violate Anthropic's terms) · Google Gemini + Vertex AI · Devin (OAuth) · DeepSeek · Moonshot AI · Zhipu AI · Z.AI · MiniMax · xAI (API key and Grok OAuth) · NVIDIA · OpenRouter · Ollama · custom OpenAI-compatible endpoints.

Clients call a Model ID you define — map it to one or more upstreams in priority layers: requests go to the top layer first, balanced by traffic or preferring the fastest target, and a conversation sticks to what worked before. A built-in catalog keeps provider model lists up to date.

When an upstream service is temporarily unavailable, Stravia retries or switches services according to your route configuration. The management UI shows each target's availability.

Platform tools and built-in agent runtime

• StraviaRead — one tool, one path: read files, webpages, search:// questions, and images; Office documents (DOCX/XLSX/PPTX/DOC/XLS/PPT) read as extracted Markdown; long results page through automatically.
• Web Search — use the Local agent loop with a browser-backed Local source, Exa, or Zhipu, or bind an External Route whose Vendor plugin returns a complete cited report.
• Media Understanding — describe images and extract text (JPEG/PNG/WebP) or answer questions about Office documents with the vision model you choose.
• Media Generation — generate or edit an image through a saved Route backed by a capable Vendor plugin, then reuse its Artifact Reference in later tools.
• Expose everything over POST /mcp, or add it to compatible requests automatically. Loops run under hard time, turn, token, and tool budgets.

Image generation

In Advanced Features → Media Generation, bind a saved image-output Route with eligible image-generation targets, then enable the capability. Bundled Codex OAuth and image-only plugins use the same Route mechanism; actual availability remains subject to upstream account and model support.

Availability depends on upstream account and model support. Size preferences do not guarantee exact dimensions, and retries may consume additional quota. See the Media Generation documentation for configuration, examples, and limits.

Vendor plugins

All model Vendors run as self-contained Wasm Components. Stravia embeds the base Vendor; Codex, Claude Code, Grok, Command Code, and Devin are dedicated plugins distributed as separate Release attachments. Import the corresponding local .wasm file in Vendor Plugins before adding a connection. Dedicated plugins own their full supplier identity and never fall back to the base package.

Vendor Plugins also supports local plugin updates without a marketplace. A plugin is trusted with the selected connection's upstream credentials and approved network destinations, so review its source and requested origins before use. See the plugin design for setup, supported capabilities, isolation, updates, and lifecycle details.

Keys, usage, and request history

• Built-in console chat: choose an API Key and model in the management UI, stream multi-turn replies, and revisit local conversation history. See Console Chat for storage and tool-injection limits.
• API keys with custom secrets, model bindings, expiry, and per-key limits for concurrency, MCP access, and automatic tool injection.
• Request Records: watch every interaction live on a zoomable canvas — model calls, retries, and tool calls — with a separate failed-requests list and a per-conversation view.
• See the token usage and provider quotas that services actually report.
• Turn on Debug to capture HTTP/SSE/WebSocket traffic and download it as a debug bundle; only HTTP Authorization values are masked, while other credentials, content, and media may be retained. Treat bundles as sensitive; see the Request Records design.
• Ordinary request observations use the same filtering even with Debug off: only actual HTTP Authorization header values are masked (case-insensitive header name), not similarly named body or tool fields. Live views, saved records, and exported events may retain download grants and other raw credentials. This does not expand ordinary capture into full wire recording, rewrite old records, or change retention, permissions, process-log/client-error filtering, or model-side credential protection. Download grants are not automatically refreshed or renewed.

Credential protection

Off by default — turn it on once and it covers every Stravia API key, with nothing to change in your clients.

• Secrets stay on your machine — Stravia recognizes API keys, tokens, and other credentials in messages, history, and tool inputs and outputs bound for a model, and swaps them for placeholders before the request goes out. All 461 detection rules are bundled and run locally — nothing is sent anywhere to be checked.
• Replies still work end to end — when a provider echoes a placeholder back, Stravia restores the real value in the answer and in tool calls, so tools can keep using the credential. The same secret keeps the same placeholder across conversations and restarts.
• Fails safe, never silently — if detection or storage breaks, the request fails instead of shipping your plaintext. Turning it off stops new replacements; placeholders already issued still restore until they expire.
• Visible and testable — browse the full rule list, see which credentials each request caught, and try your own text against the detector — test input stays on this instance and is never saved.

Good to know: it catches what its rules know — not every secret, and not personal or business data. It can over- or under-match and doesn't scan images or attachments. Tools receive the real credential when they run, so keep tool permissions and outbound limits in place — this lowers exposure, it isn't a lock.

Storage and deployment

• SQLite or PostgreSQL, chosen at first-run setup; files in local storage or S3. Existing PostgreSQL installations must also configure Redis before upgrading; see cache and Server configuration.
• Instance data lives in one directory for easier management. Back up its database and local files—including installed plugin Components—together; a remote PostgreSQL backup alone is incomplete. Before migrating or upgrading, review the deployment and storage documentation for backup and version compatibility requirements.
• One port serves the model APIs, MCP, the admin API, health checks, and the built-in management UI; deploys cleanly behind a reverse proxy.

Deployment modes

The same Rust core powers both; the management surface is the same WebUI.

Documentation

• Architecture and design documents · ADRs
• Database schema: PostgreSQL · SQLite · Changelog

Development

Rust toolchain: rust-toolchain.toml · Bun 1.4.2 · Task 3.52.0 · uv for Python E2E.

Project JavaScript development, build, and test commands use Bun. Rust and Python tests retain their native runners.

License

Stravia is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).
Separately licensed components retain their own terms: stravia-web-access is CC0-1.0 AND MIT (Cargo.toml); its browser stealth scripts retain their MIT license. Bundled fonts retain their respective licenses.

Star History