A self-hosted multi-provider AI gateway.
Cartethyia gives AI clients one stable, OpenAI- and Anthropic-compatible endpoint while the gateway handles the operational work behind it: provider-aware translation, account selection, health-aware failover, quota and cooldown enforcement, usage accounting, telemetry, and optional proxy pools.
Configure provider accounts once, issue an API key, and point OpenCode, Droid, Cline, Claude Code, Codex, or any compatible client at Cartethyia. The client keeps its native protocol; Cartethyia normalizes the request, selects a viable route, dispatches upstream, and returns the response in the contract the client expects.
Built with Bun, TypeScript, Elysia, embedded SQLite or external PostgreSQL, and optional Redis coordination.
Repository availability
The primary repository (
risunCode/Cartethyia) is currently hidden from public view. GitHub restricted it after automated star activity looked like vote manipulation rather than real interest — the project itself is unaffected, and this was not a code, security, or licensing issue.Until it is restored, use one of these. They carry the same history and the same releases:
- GitHub (mirror): https://github.com/risunCodex/Cartethyia
- GitLab: https://gitlab.com/risuncode/cartethyia
- npm: https://www.npmjs.com/package/cartethyia
Stars and forks are appreciated on the mirror, where they can actually be counted. The dashboard and console link to the mirror by default so release checks keep working while the primary is hidden.
You need Node/npm and Bun 1.4.0 or newer.
npm install -g cartethyia
cartethyia setup
carteInstall it globally. A local npm install cartethyia puts cartethyia and
carte in ./node_modules/.bin/, which is not on your PATH — the commands
will not be found. Either install globally, or run a local one through
npx cartethyia.
Update and remove:
npm update -g cartethyia # update
npm uninstall -g cartethyia # uninstallFull install guide, modes, Docker, VPS, systemd, and the one-shot script:
the installation guide. To remove it:
npm uninstall -g cartethyia.
- Speaks the provider's own dialect. Per-provider adapters reproduce the client identity, headers, and billing signals the provider expects.
- Routing looks at health. Model, alias, combo, capability, account state, cooldown, quota, and whether the provider is up — one decision, one plan.
- A retry still counts. Failover does not skip admission, usage, quota, or telemetry; failures stay distinct instead of collapsing to one 502.
- You can see the whole hop. Bounded, redacted capture of what the client sent, what Cartethyia translated, what the provider returned, and what the client got.
Full list, with the custom-built capabilities and how they differ from plain forwarders: Why Cartethyia.
One install, one console: watch traffic land, watch accounts stay healthy, and change routing without restarting anything.
 Overview Health of the whole install at a glance |
 Usage Volume, latency, cached tokens, spend per model |
 Provider detail Accounts, quota, health, and routing controls per provider |
 Model Lab Chat a routed model through the real gateway path |
 Customization Background, transparency, and per-surface blur |
 Settings Backup, retention, payload capture, update checks |
| Route | For |
|---|---|
/v1/chat/completions |
OpenAI-style chat |
/v1/responses |
Responses API, including Codex tools |
/v1/messages |
Anthropic Messages, including Claude Code |
/v1/models |
What this key can call |
/v1/completions |
Legacy text completions |
/v1/responses/compact |
Responses compaction |
/v1/search |
Web search |
/v1/systemone |
System One |
/v1/images/generations |
Image generation |
/v1/videos/generations |
Video generation |
/v1/embeddings |
Embeddings |
/v1/audio/transcriptions |
Speech to text |
/v1/audio/speech |
Text to speech |
Generation routes take an opaque body and let the provider's own adapter shape
it, so what a given model accepts is whatever that provider accepts. Images are
served by Gemini, Antigravity, Codex, and the Buddy family. Video is narrower:
among bundled providers only CodeBuddy and WorkBuddy declare it, via
seedance-2.5, submitted as an async task the adapter polls to completion
rather than returning a clip inline. A custom provider is not restricted to
those: any upstream you point it at can serve either route, and the remote's
own error is what comes back if it does not.
Embeddings and both audio routes are passthrough: the gateway routes them, applies admission and accounting, and forwards the body untouched. No bundled adapter implements them — there is no wire here to translate — so they are useful against a compatible upstream you configure yourself, and a model row carrying the matching service kind is all that is needed.
A custom provider gets every service kind automatically, including these three: it has no manifest row narrowing it, and you chose its base URL. The upstream still decides what it actually answers — pointing one at a host that does not speak a surface gets that host's own error, not a gateway refusal.
The route picks the wire. After that, routing, admission, retry, and accounting are the same.
Same app either way. Lite is not a cut-down edition.
| Pick it when | |
|---|---|
| Lite | One person, one machine, or you just want it running |
| Full | Several people, a VPS, or the process is busy enough that SQLite is the bottleneck |
Docker Compose defaults to Full. A local .env defaults to Lite. When Lite
gets tight, export a JSON backup and restore it into Full. You do not rebuild
the config.
Details: Database modes and configuration.
GNU GPL v3.0 only. You can use, change, and share it. If you ship a build or a fork, ship the source with it, under the same license. No warranty.