Pystino

A self-hosted OpenAI-compatible gateway with per-user and per-group accounting, quotas, redaction and OIDC sign-in, plus the console that operates it. The name is pistino: Turin dialect for a nitpicker, the person who checks every last detail.

One origin: the gateway serves the /v1 API, the management API and the console at /console. It pairs with Cerea, the chat, which is a /v1 client of this gateway: each runs on its own, and together they are the intended setup (see the rest of the stack).

The four ideas that carry the design

1. PostgreSQL is the ledger of record; Valkey is a rebuildable cache. Quotas still evaluate correctly with Valkey gone, just more slowly. Nothing about money is stored only in a cache.
2. Quota check before the upstream call, accounting after, a reservation in between. Without the reservation, concurrent requests each read the same under-limit total and collectively blow the budget.
3. Accounting never silently reports zero. Usage is forced out of the upstream, and if it never arrives the tokens are counted locally and the row is stamped estimated.
4. A plugin returns facts and never computes money. Vendor quirks live in gateway/plugins/; the arithmetic stays in accounting/cost.py, the only code that multiplies a count by a rate.

Where to go next

• Configure opencode with Pystino: one command points the opencode coding agent at your gateway.
• Getting started: run it, add a model, make a first billed request, sign in to the console.
• Gateway: every surface, the two authentication schemes, and the streaming traps.
• Accounting and quotas: the three cost figures, the two prompt conventions, and what money looks like end to end.
• Model aliases, Billing groups and Bring your own key: one name over several providers, who pays, and users' own providers.
• Provider catalogue and Decision models: the providers Pystino knows (including Melious), the model kinds (chat, embedding, rerank, decision and the rest) and the typed-question models.
• Redaction: the engine, the policy model, and why a scope can only tighten.
• Deployment: the Pystino-only compose deployment, TLS, identity, upgrades and backups.
• Identity: one provider from .env, who is an administrator, linking, merging, and break-glass. Bundled accounts is the Users page; the OIDC provider is registering your own issuer.
• Coding agents: what the gateway provides to agents on users' own machines.
• The console: a map of the admin screens, and which page explains each.
• Changelog: what changed in each release and which Cerea it pairs with.
• Operations and Measured performance: verifying a change, the live checks, and what the gateway costs.
• Development: toolchains, git hooks, every test layer, CI, releasing, and the repository's conventions.

The rest of the stack

Pystino is one of two repositories, each solving a different problem: Pystino governs model calls (access, cost, quotas, redaction), and Cerea is the chat users use, with its own documentation (using it, the agent machines, configuration). Its kit/ directory is the deploy kit, the deployment that runs both, with its README as the runbook.

Versions

This site follows main and is not versioned per release. What changed between releases, and which Pystino and Cerea versions a given release of the stack pins together, is recorded in the deploy kit's CHANGELOG.

Licence

Apache-2.0 for all first-party code. Dependencies must be OSI-licensed, without a CLA or an open-core model.