Yabanin, a self-hosted gateway for model access, routing and a signed record

Yabanin Core is a self-hosted AI gateway. Connect applications through OpenAI-compatible or Anthropic-compatible APIs, route requests to model providers, manage access and budgets, and inspect request logs and usage.

This is a Developer Preview. Read the release notes before deploying it with production traffic.

One API for multiple providers. OpenAI-compatible and Anthropic-compatible endpoints, streaming, and tool calling; bring your own provider keys with BYOK. See client compatibility for endpoint coverage.

Automatic model routing. Match prompt complexity to cheap, mid, or premium model pools, balance requests across pool members, and override routing per organization. Inspect the final model choice and routing reasons through X-Yabanin-Decision. Task classifier

Retries and fallback. Retry eligible failures, switch to configured fallback models, and use circuit breakers for failing upstreams. Request path

Exact and semantic caching. Reuse cached responses with streaming replay; optional semantic matching uses an embedder and pgvector. Caching

Access and spend controls. Organization roles, API keys, rate limits, credits, and budget caps keep shared model access manageable. Organization setup

Usage beyond dollars. View recorded USD cost, wallet credits, tokens and factor-based CO₂e estimates in one organization-scoped report. Keep scenario costs separate from recorded spend, with data-quality labels and coverage notices. Usage and impact accounting

Versioned pricing with provenance. Inspect the active price catalog, preview a replacement and promote a reviewed pricing pack. Catalog versions, digests and source dates make cost calculations traceable. Pricing and accounting

Programmable guardrails. Compose YAML policies for PII, secrets, and prompt injection checks, masking, external scanners, and LLM judges. Preview decisions in shadow mode before enforcement; the pipeline is opt-in. Policy pipeline

Agent governance. Give agents separate identities, daily budgets, task token limits, and delegated keys; control supported tool and MCP calls with tool policies. Agent governance

Usage visibility and offline audits. Inspect request history and usage in the React dashboard, manage the gateway through the admin API and yb CLI, and simulate cache reuse and cheaper routing from local logs. Export Markdown, JSON or a standalone HTML report without a running gateway or provider calls. Offline spend audit

Signed request records. Optional Ed25519-signed lineage preserves model and region-related claims in a tamper-evident ledger. Signatures verify record integrity, not the physical location of inference. Lineage

Costs depend on configured prices and recorded usage. The bundled reference prices have limited coverage and may be outdated. Configure current prices before relying on cost reports. The mock quickstart makes no paid provider calls.

The dashboard's Budgets → Units & spend view keeps five quantities separate:

Carbon factors must be supplied by the operator; the quickstart does not include a populated emissions catalog. CO₂e is a model-based estimate, not a hardware measurement. Carbon-cap status is informational, and this view does not measure water or electricity consumption. Monetary accounting remains USD-based; credits and tokens are separate units, not foreign-exchange conversion. See the calculation and coverage details.

Start the whole local stand — gateway, PostgreSQL, Redis, a mock model provider, and the dashboard UI — with one Compose stack. No provider account or paid inference is needed. The mock returns sample responses so you can try the API, request logging, and the dashboard. Nothing listens on 0.0.0.0.

You need Docker with Compose v2, Git, Bash, OpenSSL, curl, and Python 3. On Windows, use WSL2 with Docker integration. Keep localhost ports 3000 (dashboard), 8082 (gateway), and 8086 (admin API) and Docker subnet 10.207.0.0/24 available. The first build downloads Go modules and container images; you do not need Go or Node.js installed on your computer (see First-start timing).

bash scripts/quickstart/demo.sh runs the steps below for you: configure, build, start, seed, then a summary pointing at the dashboard and where the API key and admin password were printed. Rerunning it is safe; --fresh wipes the demo database and issues new credentials (destructive). The numbered steps are the manual path that explains each command.

git clone https://github.com/yabaninai/yabanin-core.git cd yabanin-core

bash scripts/quickstart/init-env.sh

docker compose -f deploy/quickstart/docker-compose.yml
--profile mock --profile ui build
--build-arg SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"

docker compose -f deploy/quickstart/docker-compose.yml
--profile mock --profile ui up -d --no-build --wait

The mock profile adds the mock provider; the ui profile adds the containerized dashboard on http://127.0.0.1:3000. Omit --profile ui for a leaner stack without the dashboard. Configuration is saved in deploy/quickstart/.env; keep this file with your database between restarts.

bash scripts/quickstart/seed.sh

Save the gateway API key and admin password printed by the command. They are shown once. The default admin email is admin@localhost.

read -r -s -p "Gateway API key: " YABANIN_API_KEY printf '\n'

curl --fail-with-body --silent --show-error
http://127.0.0.1:8082/v1/chat/completions
-H "Authorization: Bearer $YABANIN_API_KEY"
-H 'Content-Type: application/json'
--data '{"model":"mock-model","stream":false,"messages":[{"role":"user","content":"Hello from Yabanin"}]}'

You should receive a chat response with choices[0].message.content. Check model discovery, chat responses, and request logging together:

bash scripts/quickstart/smoke.sh "$YABANIN_API_KEY"

4. Open the dashboard

Open http://127.0.0.1:3000 and sign in with the admin credentials from step 2 (default email admin@localhost). The dashboard container serves the built UI and proxies /api and /auth to the admin API on the same origin, so no local Node.js and no CORS configuration are needed. Port 8086 serves the admin API itself; it does not serve the dashboard.

The full quickstart covers organization membership, request history, real providers, and troubleshooting. To iterate on the dashboard source with hot reload, install Node.js 22 and npm and run in another terminal:

npm ci --prefix web/dashboard npm --prefix web/dashboard run dev -- --host 127.0.0.1

Then open http://127.0.0.1:5173.

To stop the stack while keeping its database:

docker compose -f deploy/quickstart/docker-compose.yml
--profile mock --profile ui down

First-start timing

With images built once, up -d --wait finishes in about ten seconds, and the mock-openai container itself starts in under a second (its health check polls every two seconds). If the stand appears to hang on the mock, it is waiting on image transfer or build, not on the service. The first start is dominated by three things:

Restarting later reuses the layer cache and the named database volume, so up returns in seconds.

Task Guide

Understand the request path Introduction · Architecture

Connect an application Compatibility · SDKs

Set up access and provider keys Organizations · BYOK

Configure routing and policies Providers · Pipeline

Understand cost, credits, tokens and CO₂e Usage and impact accounting

Inspect a local request log Spend audit · CLI

Deploy and operate Deployment · Production runbook

Build and contribute Development · Contributing

Build from source

Use the Go version declared in go.mod, Git, and make:

make unified yb ./yb --help

yabanin runs the server components, migrations, and bootstrap commands. yb provides operator commands. For service configuration and tests, see Development.

Keep provider credentials and the generated .env file out of Git. The quickstart is a local demonstration; use deployment-specific secrets and network settings for production. See SECURITY.md to report a vulnerability and the release notes for known issues.

Yabanin Core is licensed under Apache-2.0, copyright 2026 Dmitry Lakhvich. Commercial use, modification, and redistribution are permitted under that license. Third-party materials retain their own terms; see NOTICE and LICENSING.md. The license does not grant rights to the Yabanin trademarks beyond its terms.