A key per caller
Create a virtual key for each app. The ledger groups requests by key as well as by app label, so a shared name never hides which key made a call.
The quiet layer between your apps and models
Know the caller behind every request.
tokenflow is a self-hosted, OpenAI-compatible LLM gateway. Give each app its own virtual key, point them all at one base URL, and read a per-request ledger of reported usage — with every dollar figure labeled for what it is: an estimate.
The real dashboard after 42 requests from three virtual keys, sent through tokenflow to a local test upstream. Two calls used a model with no configured rate, so they're counted — and left out of the dollar totals.
What it does
A clear path from request to record.
tokenflow sits in front of an OpenAI-compatible upstream — a gateway like Bifrost, or a provider directly — and adds keys, a ledger and a dashboard.
One OpenAI-compatible URL
Apps set LLM_BASE_URL and a virtual key. Chat completions (streamed or not), model listing and audio transcription all proxy through.
Your app key stops here
The virtual key authenticates against the gateway only. The provider sees just the credential configured for the route a model resolves to.
A ledger of every call
Time, app, model, route, tokens and cost basis for each request, rolled up by model, key and app on the overview.
Budgets per key
Give a key a maxBudgetUsd. Once its recorded estimates reach it, the gateway answers 429 insufficient_quota without calling the provider.
Streams stay streams
Streaming responses pass through unmodified, except for the usage chunk tokenflow requests so the call can be metered. Errors keep the OpenAI envelope.
Honest costs
Let unknown stay unknown.
A gateway that turns missing data into $0 invents savings. tokenflow keeps the gaps visible.
Estimates, not invoices
Dollar figures come from a local list-price rate table and the usage the provider reported. They never claim to match a bill.
Gaps stay gaps
Reported zero usage stays zero. Missing usage, an unknown model rate and older unverified amounts are each labeled and kept out of comparable totals.
Budgets aren't spend caps
One completed call can exceed a key's remaining allowance. An unresolved ledger write keeps the key closed until you reconcile it.
Subscription routes are opt-in
Off by default. When on, flagged models go to a proxy you run and are recorded at a $0 route-cost assumption — never a verified charge.
Run it
From a checkout to your first request.
tokenflow runs on your machine with Bun, in front of an upstream you choose. Then open the setup page, create a key, and point an app at the gateway.
Start the gateway and dashboard
bun install
cp .env.example .env # local-only sign-in bypass
bun run db:migrate
bun run seed
UPSTREAM_BASE_URL=<your-openai-compatible-upstream> bun run dev
Open http://localhost:52813/welcome, create a key, then set your app's LLM_BASE_URL=http://localhost:52813/v1 and LLM_API_KEY.