Skip to main content

Local Quickstart

Run GenAI Smart Router on a laptop or workstation in about ten minutes. This path is for local development: one OpenAI Chat upstream, one static model group named local, SQLite with auto-safe migrations, and an operator-issued runtime license.json. Packaged production installs use Installation and config.example.yaml.

The software is Apache-2.0. The signed license.json is an operator runtime policy file, not a copyright license.

Prerequisites​

  • Go as declared in go.mod
  • Python 3 for the bootstrap script
  • An OpenAI API key for one Chat completion (or change the starter provider later)

Bootstrap​

From a clone of metrum-ai/router:

python3 scripts/local_dev_bootstrap.py --out-dir tmp/local-dev

The script copies config.minimal.example.yaml and env.minimal.example.json, issues a license for the checked-in docs/entitlement.local-dev.example.json (sku: oss-self-managed) using metrum-genai-smartrouter-license, and merges one hashed caller with metrum-genai-smartrouterctl callers generate --write. It does not print the private signing key or the raw caller token. The token is in tmp/local-dev/router.token (mode 0600).

Fill the provider key. env.json next to the config is loaded automatically:

# edit tmp/local-dev/env.json and set OPENAI_API_KEY

Keep tmp/local-dev/ out of git. tmp/ is gitignored.

Start And Smoke​

go run ./cmd/metrum-router --config tmp/local-dev/config.yaml

In another terminal:

export ROUTER_BASE_URL="http://127.0.0.1:8080"
export ROUTER_TOKEN="$(tr -d '\n' < tmp/local-dev/router.token)"

curl -fsS "$ROUTER_BASE_URL/readyz"
curl -fsS -H "Authorization: Bearer $ROUTER_TOKEN" \
  "$ROUTER_BASE_URL/v1/models"
curl -fsS -H "Authorization: Bearer $ROUTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local",
    "messages": [{"role": "user", "content": "Reply with exactly: router ok"}],
    "max_tokens": 16
  }' \
  "$ROUTER_BASE_URL/v1/chat/completions"

/v1/models is the source of truth for the model value. The starter group is local. Do not echo $ROUTER_TOKEN into tickets or chat.

Client-only examples against an already running deployment: API Quickstart. Codex and Claude Code: Codex CLI and Claude Code CLI.

Hybrid And Production Next Steps​

The same governance model (caller tokens, model groups, server-side keys, usage rows) applies on-prem, in a cloud VPC, or hybrid: private vLLM/SGLang plus commercial APIs. See the overview hybrid diagram and Self-Hosted Upstreams. For learned cheapest-sufficient routing, see Train And Serve Learned Routing Policy.