Your AI. Your Models. Your Rules.
An open-source, self-hosted AI gateway to route, manage, and optimize multiple LLM providers through a single API.
Screenshots · Install · Connect your apps · Host it on a server · Settings · FAQ · Changelog · GitHub
Add your AI providers once in a web dashboard, create API keys, and point any OpenAI- or Anthropic-compatible app at one base URL: Claude Code, Codex CLI, the OpenAI and Anthropic SDKs, and other tools. A combo is one model name that tries several provider models in order, or with another routing strategy, and falls back on errors and usage limits.
Claude Code ─┐ ┌─► OpenAI
Codex CLI ─┤ ├─► Anthropic
Your app ─┼─► TRouteAI (one /v1 API) ───┼─► Gemini, Groq, Mistral, …
Any SDK ─┘ keys · combos · fallback └─► any OpenAI- or Anthropic-compatible server
usage limits · logs
Status: stable. 1.0.9 is the first stable release. Versions 1.0.0 to 1.0.8 were beta
releases; if you run one of them, update with trouteai update.
npm install -g trouteai
trouteaiOpen http://localhost:20017 and sign in with the first password (the terminal shows where it is
saved). Add a provider, create an API key, and point your app at http://localhost:20017/v1.
Install has the details, Host it on a server the steps for a
server.
- One API for every provider. OpenAI format (
/v1/chat/completions,/v1/responses,/v1/models, embeddings, images, audio) and Anthropic format (/v1/messages). 290+ built-in providers by API key or account sign-in, plus any OpenAI- or Anthropic-compatible server. - Combos with fallback. In order, round robin, weighted, cost-optimized and 15 more routing strategies. An account whose usage limit (5-hour, weekly, daily) is used up is skipped without a request until it resets, then used again by itself.
- Made for coding agents. Claude Code model discovery, effort and thinking settings passed through, the conversation sent exactly as the client built it, and context-limit errors returned in the wording the agent recovers from (it compacts and goes on).
- Lite and private. Runs on your computer or server (Node.js and SQLite), near-zero CPU when idle, provider credentials encrypted at rest, no telemetry, a random admin password on first start.
- Easy, and yours. One
npm install -g, a clean dashboard with light and dark themes, and your own app name, logo and credit line.
Apps: Claude Code, Codex CLI, the OpenAI and Anthropic SDKs (Python, JavaScript and others), curl, and any tool that lets you set an OpenAI or Anthropic base URL.
Providers: OpenAI, Anthropic, Google Gemini, OpenRouter, DeepSeek, Groq, Mistral, xAI (Grok), Together AI, Fireworks AI, Perplexity, Ollama on your own computer, and 290+ more by API key or account sign-in. Any OpenAI- or Anthropic-compatible server can be added as a custom provider.
You need Node.js 26 (recommended), 24, or 22.22.2 and newer.
npm install -g trouteai --allow-scripts=tls-client-node,koffi --loglevel=error
trouteaiThe extra options keep the install quiet and let the two TLS helpers of the browser-session
providers (ChatGPT Web, Claude Web, Grok Web, Perplexity Web) finish their setup. Plain
npm install -g trouteai works too; newer npm versions then print a note about install scripts.
Open http://localhost:20017 and sign in. On the first start TRouteAI creates a random
dashboard password and saves it to initial-admin-password.txt in the data folder (the start
screen shows the exact path). Stop TRouteAI with Ctrl+C.
| Command | What it does |
|---|---|
trouteai |
Start TRouteAI |
trouteai --port 20018 |
Start on another port |
trouteai config |
Show your settings |
trouteai config set PORT 20018 |
Change a setting |
trouteai reset-password |
Set a new dashboard password |
trouteai update |
Update to the latest version |
trouteai uninstall |
Remove TRouteAI |
trouteai --help |
All commands and options |
trouteai update installs the latest version with a progress line (stop TRouteAI first).
trouteai uninstall removes TRouteAI; it keeps your data folder unless you answer yes.
All settings are in one file, .env in the data folder (~/.trouteai/.env; on Windows
%APPDATA%\trouteai\.env unless ~/.trouteai exists). trouteai creates it on the first start:
| Setting | Default | Meaning |
|---|---|---|
PORT |
20017 |
Port for the dashboard and the API |
HOST |
0.0.0.0 |
0.0.0.0 = this computer and your network, 127.0.0.1 = only this computer |
INITIAL_PASSWORD |
empty | Password for the first login (8+ characters); empty = random password file |
REQUIRE_API_KEY |
true |
Apps must send an API key created in the dashboard |
NEXT_PUBLIC_BASE_URL |
empty | Your public address behind a domain, for example https://ai.example.com |
Edit the file or run trouteai config set KEY VALUE, then restart TRouteAI. Command-line
options win over environment variables, which win over the file. --data-dir <folder> (or the
DATA_DIR environment variable) keeps settings and data in another folder. Secret keys are
generated automatically in server.env next to the settings file; keep both files private.
The terminal shows only warnings and errors. trouteai --verbose (or APP_LOG_LEVEL=info) shows
every message; all logs are also written to logs/ in the data folder. The app log rotates at
10 MB and keeps 3 old files (APP_LOG_MAX_FILE_SIZE, APP_LOG_MAX_FILES). Request detail files
are kept 7 days and at most 300 MB in total, oldest removed first (CALL_LOG_RETENTION_DAYS,
CALL_LOG_MAX_TOTAL_MB). trouteai limits server memory to 35% of RAM (512 MB to 4 GB); raise
it with TROUTEAI_MAX_HEAP_MB if the log shows "JavaScript heap out of memory". npm start /
app.cjs use node --max-old-space-size=N instead.
- Open the dashboard and log in.
- Home shows a short "Get started" checklist that links to each step below. It also shows the base URL, API key and model to paste into your app.
- Providers → pick a popular provider and paste its API key, or use Step-by-step setup (API key, account sign-in, or a custom OpenAI/Anthropic-compatible server).
- API Keys → create an API key (
sk-…). It is shown once, with copy buttons. - Combos → create a combo, for example
my-combo=openai/gpt-4o-mini→anthropic/…("In order" = try the first model, fall back to the next on errors or limits). - Use it from any client (on a server, replace
http://localhost:20017with your address):
curl http://localhost:20017/v1/chat/completions \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{"model":"my-combo","stream":false,"messages":[{"role":"user","content":"Hello"}]}'- OpenAI-compatible base URL:
http://localhost:20017/v1(/chat/completions,/responses,/models,/embeddings,/images/generations,/audio/*, …) - Anthropic-compatible:
http://localhost:20017/v1/messageswith headerx-api-key: sk-your-key modelcan be a combo name or aprovider/modelid fromGET /v1/models- Requests without
"stream"are streamed by default; send"stream": falsefor a JSON reply (or switch the key to JSON mode in API Keys)
The sidebar starts with a simple menu (main pages only). Use Show all menus at the bottom of the sidebar to see every page.
export ANTHROPIC_BASE_URL="http://localhost:20017" # no /v1: Claude Code adds /v1/messages
export ANTHROPIC_AUTH_TOKEN="sk-your-key"
export ANTHROPIC_MODEL="my-combo"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 # /model lists your TRouteAI models
claudeThe Endpoint page in the dashboard shows these lines with your own address, and examples for curl, Python, JavaScript and the Anthropic API.
Use http://localhost:20017/v1 as the base URL and an API key from the dashboard; the model is
a combo name or a provider/model id. Codex CLI talks to /v1/responses.
SixPanel is a free hosting control panel that turns a server you rent (a VPS) into your own hosting platform. It installs TRouteAI straight from npm:
- Nothing is built on the server. A deploy downloads the prebuilt
trouteaipackage, checks it against the checksum npm publishes and installs it in about 15 seconds. - Nothing to configure. The package carries its own
sixpanel.json: the start command, the health check, the data folder to keep and the secret keys to generate. - HTTPS is free and renews itself.
- The data folder is kept between deploys and is part of SixPanel's backups.
- A new version goes live only after it answers, and you can roll back from the Deploys page.
You need a fresh Ubuntu 26.04 LTS (recommended), Ubuntu 24.04 LTS or Debian 13 server (x86_64 or arm64) with root access and at least 1 GB of memory (2 GB recommended), and a domain name pointed at the server.
-
Install SixPanel as root, as the install guide explains:
curl -fsSL https://installer.allsweb.net/sixpanel/install.sh | sudo bash -
In SixPanel, open Projects, press Create a new project and choose Node.js app. Under Where is the code? choose From an npm package and type
trouteai. SixPanel installs and starts it by itself. -
On Domain & SSL, add your domain.
-
Open
https://your-domainand sign in. The first password is a random one: open the website's Terminal in SixPanel and read it withcat .trouteai-data/initial-admin-password.txt.
.trouteai-data/ holds the database, logs and backups; SixPanel keeps it between deploys. SixPanel
makes the three secret keys once, on the server, and they never change after that. TRouteAI runs
as one process on purpose: it keeps live connections and timers in its own memory.
Updates. When a newer version is on npm, the website's Deploys page says so and shows a
Deploy button; Automatic deploys on the same page installs new versions by itself
(trouteai update is not used on SixPanel). To stay on one version, choose it there instead of
latest, for example 1.0.9.
Password. To set a new dashboard password, run
DATA_DIR=.trouteai-data npm exec --no -- trouteai reset-password in the website's Terminal.
Moving an existing website. A TRouteAI website made from an uploaded folder or a git branch
can switch: make a backup, then on Deploys choose An npm package → Choose a package
and type trouteai.
Everything else about SixPanel is in its documentation.
These panels build TRouteAI from its source code. A Linux build needs about 4.6 GB of memory; on a smaller server, build on your own computer and upload the result (step 4).
-
Upload the project folder (without
node_modulesand.build) and select Node.js 26 (24 or 22.22.2+ also work). -
Create
.envfrom.env.example(npm installdoes this for you) and set:INITIAL_PASSWORD: a strong dashboard password (8+ characters). If you leave it empty, a random one is generated on first start and saved toDATA_DIR/initial-admin-password.txt.NEXT_PUBLIC_BASE_URL=https://your-domain: your public URL.PORT: the port your panel assigns or proxies to (default20017).- Optional
DATA_DIR: where the SQLite database lives (default~/.trouteai). - Behind a reverse proxy (nginx, Caddy, Cloudflare, or a panel's built-in proxy) that
terminates HTTPS, set
TROUTEAI_TRUST_PROXY=loopback(proxy on this machine) orprivate(proxy on the LAN). The app then trustsX-Forwarded-Proto/X-Forwarded-For, so the login cookie is markedSecureand the real client IP is used for rate limiting and the IP filter. Leave it unset only for a direct (no-proxy) deployment, where clients could fake those headers.AUTH_COOKIE_SECURE=trueforces theSecurecookie on its own.
Upgrading an existing reverse-proxy install? Set
TROUTEAI_TRUST_PROXY(orAUTH_COOKIE_SECURE=true). Earlier versions trustedX-Forwarded-Protounconditionally; it is now gated so a direct public deployment cannot be spoofed. -
Install dependencies:
npm install(or the panel's "Run NPM Install" button). If the panel installs withNODE_ENV=production, usenpm install --include=dev, because the build tools are dev dependencies. -
Build:
npm run build. If the server does not have enough memory, runnpm run buildon your own machine and upload the generated.build/folder instead. -
Start the app:
- panels with a start command:
npm start - panels with an application startup file:
app.cjs
- panels with a start command:
-
Point the domain at the app port (the panel's reverse proxy / "Node.js app URL") and enable SSL. With your own nginx config, keep
proxy_buffering off;for the app so streaming works.
Restart the app after changing .env. Data (database, logs, backups) stays in DATA_DIR, so you
can redeploy the code without losing providers, keys or combos.
git clone https://github.com/allswebtech/trouteai.git
cd trouteai
npm install # also creates .env from .env.example with generated secrets
npm run build
npm start # http://localhost:20017Development mode: npm run dev. A source checkout reads its settings from the project .env.
The tests need no account and no API key: npm test after a build (see
tests/README.md).
The app shows no third-party branding, sponsor or affiliate links. Change the app name and logo
in Settings → Appearance. To show your own credit line in the sidebar footer and on the login
page, set it in .env and restart the app:
BRAND_CREDIT="Your credit line"
BRAND_CREDIT_URL=https://your-website.example # optional linkLeave BRAND_CREDIT empty to hide it (the default).
- The dashboard always requires a password; a first-run setup without a password is only possible from the server itself, never from the internet.
/v1requires an API key from the dashboard (REQUIRE_API_KEY=true).- Login attempts are rate-limited; session cookies are
HttpOnly,SameSite=Lax, andSecureautomatically on HTTPS. - Strict security headers (CSP without eval, HSTS, no framing, no
X-Powered-By). - Provider credentials are encrypted at rest (
STORAGE_ENCRYPTION_KEY, generated on first start). - The dashboard and the API ask search engines and AI crawlers not to index them.
- Update:
trouteai update(stop TRouteAI first). On a hosting panel, deploy again. - Reset the admin password:
trouteai reset-password(source checkout:npm run reset-password; SixPanel: see above) - Back up the data folder (
~/.trouteaior yourDATA_DIR). It holds the database, your settings and the key that decrypts your provider credentials. - Environment variables: see
.env.example - What changed in each version: CHANGELOG.md
Bug reports, ideas and pull requests are welcome. CONTRIBUTING.md explains
how to set up the project, where things are and how to check a change. The repository is also
set up for AI coding agents (AGENTS.md, and .claude/ for Claude Code).
The source code is on GitHub: allswebtech/trouteai.
Found a security problem? Please report it privately: see SECURITY.md.
What is TRouteAI? An open-source, self-hosted AI router (an LLM gateway): one OpenAI- and Anthropic-compatible API in front of many AI providers, with API keys, combos (fallback and load balancing) and usage-limit routing, managed in a web dashboard.
Is it free? Yes, MIT licensed. You pay only your AI providers, under your own accounts.
Where do my keys and prompts go? Only to the providers you add. TRouteAI runs on your own machine or server, stores provider credentials encrypted in a local SQLite database, and sends no telemetry.
What happens when a provider hits its limit? In a combo, TRouteAI moves to the next model.
An account whose usage window is used up is skipped without sending it a request until the
window resets. When every account is limited, the client gets 429 with Retry-After.
Does TRouteAI change my conversation? No. Requests reach the provider as your client built them. Prompt compression exists, but it is off unless you turn it on in Settings. A request that is too long for the model gets the error your agent knows how to handle (Claude Code compacts the conversation by itself).
Where should I host it? On your own computer, install it with npm. On a server, SixPanel is the easiest way: HTTPS, backups and deploys you can roll back, with nothing built on the server.
Which Node.js version do I need? Node.js 26 is recommended; 24, and 22.22.2 or newer also work.
How do I reset the dashboard password? Run trouteai reset-password.
MIT. See LICENSE.





