Routiform

One AI endpoint for your apps, tools, and agents.

Routiform is a self-hosted AI gateway and dashboard for teams that want one stable integration point across 60+ providers. You send OpenAI-compatible requests to one /v1/* endpoint, and Routiform handles translation, routing, retries, fallback, and operations.

It is built for developers who want to:

• integrate once, then swap providers and models without rewriting client code
• keep Cursor, Devin, Cline, Claude Desktop, Codex, MCP clients, and internal apps on one base URL
• survive provider outages, model deprecations, and quota limits with policy-driven fallback
• reduce cost using combo routing, budget guards, and lower-cost model paths
• run their own gateway with full visibility into keys, logs, quotas, and health

Why teams choose Routiform

• One API surface: OpenAI-compatible routes for chat, embeddings, images, audio, video, rerank, search, and more
• Resilience by default: retries, multi-account failover, model-family fallback, and emergency fallback
• Cost-aware routing: weighted/priority/P2C strategies, budget controls, and quota-aware decisions
• Built for agents: MCP server (25 tools), A2A v0.3 support, memory, and skills
• Operational control: dashboard for providers, combos, keys, usage, logs, and endpoint health

Product demo

Feature demos

| Endpoint workspace | Combo routing builder | | ------------------------------------------------------- | --------------------------------------------------- | | | |

| Settings and operational controls | | ------------------------------------------------------- | | |

These screens show the day-to-day workflow: manage unified endpoints, configure routing combos with fallback policies, and control operational settings from one dashboard.

Core capabilities

Unified API gateway

• OpenAI-compatible API surface for chat, embeddings, images, audio, video, rerank, search, and more
• Request and response translation across OpenAI, Anthropic, Gemini, Devin, and provider-specific formats
• Native CLI-backed bridges for providers like Devin, including subprocess execution and streaming normalization back to OpenAI-compatible responses
• Works with local apps, server deployments, CLI tools, browser clients, and agent frameworks

60+ providers

Routiform supports a broad provider mix, including:

• OpenAI
• Anthropic
• Devin
• Google Gemini
• DeepSeek
• Groq
• xAI
• Mistral
• Fireworks
• Cohere
• NVIDIA
• Cerebras
• OpenRouter
• Hugging Face
• Cloudflare AI
• Ollama Cloud
• Together
• Perplexity
• Tavily
• Brave
• Exa
• and many more

Provider types include:

• free providers
• OAuth-backed providers
• API-key providers
• custom OpenAI-compatible providers
• custom Anthropic-compatible providers

Routing and resilience

• combo-based routing across multiple models/accounts/providers
• weighted, priority, round-robin, P2C, and cost-aware strategies
• model-family fallback and emergency fallback
• multi-account failover inside the same provider
• retry handling and resilience profiles
• rate-limit aware behavior and quota checks
• circuit-breaker style protections for unstable upstreams

Cost and quota controls

• budget-aware routing controls
• quota snapshots and health checks
• cost reporting endpoints and dashboard views
• low-cost and free-tier friendly setups
• policy-driven model selection for operational or cost goals

Built-in protocols for agent workflows

• MCP server with 25 tools and multiple transports
• A2A v0.3 support with task lifecycle handling
• memory tools for search/add/clear
• skills system for extensible agent behaviors

Dashboard and operations

• provider connection management
• model catalog and per-provider model sync
• combo editor and routing strategies
• request logs and detailed logs
• API key manager and scoped access controls
• endpoint health and metrics
• webhook and automation surfaces

Supported API surfaces

Routiform exposes a unified API under /v1/*.

Main routes include:

• /v1/chat/completions
• /v1/responses
• /v1/embeddings
• /v1/images/generations
• /v1/audio/speech
• /v1/audio/transcriptions
• /v1/moderations
• /v1/rerank
• /v1/search
• /v1/videos/generations
• /v1/music/generations
• /v1/models

See docs/API_REFERENCE.md for route details.

MCP server

Routiform ships with an MCP server for operational and routing workflows.

Included tool groups:

• health and provider status
• combo listing and switching
• routing simulation and explanation
• budget and resilience controls
• memory operations
• skill operations

Supported transports:

• stdio
• SSE
• streamable HTTP

See docs/MCP-SERVER.md.

A2A support

Routiform includes an A2A server with:

• JSON-RPC 2.0 task handling
• SSE streaming
• task lifecycle management
• skill exposure for smart routing and quota workflows
• agent discovery via /.well-known/agent.json

See docs/A2A-SERVER.md.

Why teams use it instead of wiring providers directly

• one client integration instead of many SDK branches
• self-hosted control over credentials and routing policy
• easier experimentation with new providers and cheaper models
• fewer production incidents from single-provider dependency
• operational visibility without building a custom gateway first
• ready-made agent protocol support instead of stitching MCP/A2A yourself

Quick start

Option 1: npm

Requirements:

• Node.js >=18 <25

npm install -g routiform
routiform

Open the dashboard:

http://localhost:20128/dashboard

Default API base:

http://localhost:20128/v1

Option 2: npx

npx routiform

Option 3: Docker

docker pull linhnguyen0944/routiform:cli

docker run -d \
  --name routiform \
  --restart unless-stopped \
  -p 20128:20128 \
  -p 20129:20129 \
  -p 443:443 \
  -e DATA_DIR=/app/data \
  -e INITIAL_PASSWORD="change_your_password" \
  -e DEVIN_BIN=/root/.local/bin/devin \
  -v routiform-data:/app/data \
  -v "$HOME/.local/share/devin/credentials.toml:/root/.local/share/devin/credentials.toml:ro" \
  -v "$HOME/.claude:/root/.claude" \
  -v "$HOME/.openclaw:/root/.openclaw" \
  -v "$HOME/.config/opencode:/root/.config/opencode" \
  -v "$HOME/.continue:/root/.continue" \
  -v "$HOME/.aws:/root/.aws" \
  linhnguyen0944/routiform:cli

MITM support in Docker: The MITM proxy (Antigravity, Kiro etc.) can run inside Docker but requires manual host setup since the container cannot modify your host's /etc/hosts or system keychain. After starting the MITM from the dashboard, run these on your host:

# 1. Add DNS redirect (run once)
echo '127.0.0.1 daily-cloudcode-pa.googleapis.com' | sudo tee -a /etc/hosts

# 2. Install MITM cert (copy cert from container to host, then install)
docker cp routiform:/app/data/mitm/server.crt /tmp/routiform-mitm.crt
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/routiform-mitm.crt

If you use npm install -g routiform instead, MITM works out of the box — it runs directly on your host with full DNS and keychain access.

If you want to use Devin in Docker, mount only credentials.toml from the host so the Linux CLI inside the container can reuse your existing credentials without overwriting the bundled Linux install:

-e DEVIN_BIN=/root/.local/bin/devin \
-v "$HOME/.local/share/devin/credentials.toml:/root/.local/share/devin/credentials.toml:ro"

Do not mount ~/.local/bin or the entire ~/.local/share/devin directory from macOS into the container. That can overwrite the Linux Devin binary with macOS symlinks and cause spawn devin ENOENT or binary format errors.

Option 4: source

git clone https://github.com/linhnguyen-gt/Routiform.git
cd Routiform
npm install
npm run dev

First-run flow

1. Open /dashboard
2. Add one or more provider connections
3. Pick models or sync available models from providers that support live model listing
4. Create a combo if you want fallback or multi-provider routing
5. Point your client to Routiform instead of the upstream provider directly

For Devin connections, authenticate the local CLI first with devin auth login, then import or auto-detect the credentials from the provider setup flow and sync the available Devin model catalog.

Example client configuration

OpenAI SDK compatible clients

export OPENAI_BASE_URL="http://localhost:20128/v1"
export OPENAI_API_KEY="your-routiform-api-key"

cURL

curl http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-routiform-api-key" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Hello from Routiform"}
    ]
  }'

Provider categories

Free

Examples include built-in support for free-access workflows such as Qoder AI, Qwen Code, Kiro AI, and similar sources where available.

OAuth

Examples include Claude Code, Devin, Codex, GitHub Copilot, Cursor, Cline, Kimi Coding, and other account-backed integrations.

API key

Most commercial providers fit here, including OpenAI, Anthropic, Gemini, Groq, xAI, Mistral, DeepSeek, Fireworks, Cohere, NVIDIA, and more.

Custom compatible providers

You can register OpenAI-compatible or Anthropic-compatible upstreams using custom base URLs.

Model routing concepts

Connections

A connection is one authenticated provider account or endpoint.

Models

Models can come from:

• built-in provider registries
• synced provider model lists
• custom user-defined model entries

Combos

A combo is a routing group that tells Routiform which models/providers to try and in what order or policy.

Policies

Policies influence fallback, degradation, lockout behavior, quota handling, and other runtime decisions.

Storage and backup

Routiform stores state in SQLite under DATA_DIR using better-sqlite3.

Default data directory:

~/.routiform/

Important backup note:

• back up the entire DATA_DIR
• do not copy only storage.sqlite
• server.env in the same directory contains STORAGE_ENCRYPTION_KEY, which is required to restore encrypted provider secrets correctly

See docs/BACKUP_AND_RESTORE.md.

Important environment variables

Common variables:

| Variable | Default | Purpose | | ------------------------ | ----------------------------- | -------------------------------- | | PORT | 20128 | HTTP port | | HOST | 0.0.0.0 | Bind address | | DATA_DIR | ~/.routiform | State directory | | REQUEST_TIMEOUT_MS | 600000 | Shared upstream timeout baseline | | STREAM_IDLE_TIMEOUT_MS | inherits REQUEST_TIMEOUT_MS | Max gap between SSE chunks |

Advanced timeout overrides still exist, including:

• FETCH_TIMEOUT_MS
• FETCH_HEADERS_TIMEOUT_MS
• FETCH_BODY_TIMEOUT_MS
• API_BRIDGE_PROXY_TIMEOUT_MS

Security notes

• do not commit provider keys or session secrets
• use the dashboard API manager for scoped access where possible
• protect exposed deployments with proper auth and network controls
• never log encryption keys
• validate and sanitize user-facing content when building on top of Routiform

Project structure

Top-level areas:

• src/ — Next.js app, dashboard, API routes, DB modules, domain logic
• open-sse/ — request pipeline, executors, translators, handlers, MCP server
• docs/ — user guides, architecture, API, deployment, troubleshooting
• tests/ — unit, integration, ecosystem, and protocol coverage

See docs/ARCHITECTURE.md for the deeper layout.

Development

Install dependencies:

npm install

Run locally:

npm run dev

Build production assets:

npm run build
npm run start

Useful scripts:

npm run lint
npm run typecheck:core
npm run check
npm run test:all
npm run test:vitest
npm run test:e2e
npm run test:protocols:e2e
npm run test:ecosystem

Docs map

• User Guide
• API Reference
• Architecture
• MCP Server
• A2A Server
• Auto Combo
• CLI Tools
• Backup and Restore
• Troubleshooting
• Features
• OpenAPI spec

Compatibility

Routiform is useful with:

• OpenAI-compatible SDKs
• Cursor
• Devin
• Cline
• Claude Desktop
• Codex clients
• custom MCP clients
• internal tools and gateways that want one normalized AI interface

License

MIT

Acknowledgments 🤝

Routiform wouldn't exist without the foundations laid by:

• 9router by @decolua — The original inspiration
• OmniRoute by @diegosouzapw — Expanded the vision
• CLIProxyAPI — The original Go implementation that inspired this JavaScript port

Links

• Repository: https://github.com/linhnguyen-gt/Routiform
• npm: https://www.npmjs.com/package/routiform
• Docker: https://hub.docker.com/r/linhnguyen0944/routiform