//DOCS Configuration

Configuration

Punk is configured through environment variables and tenant settings.

Local Defaults

bun install
bun run dev

Default local behavior:

• Port: 4100.
• Database: data/punk.db.
• Provider: offline mock simulator when no matching live provider key is available.
• Auth: open dev mode when PUNK_API_KEY is absent.
• Worker: embedded in the API process.
• Learning tick: every 10 seconds.
• Web fetch runtime: built-in page-to-context adapter.
• Governance: embedded policy engine with YAML policies.

Environment Variables

Provider Modes

Use mock mode for docs, demos, CI, and deterministic local testing.

Provider Keys (BYOK)

Tenants can bring their own provider API keys instead of (or alongside) the gateway's env keys. A tenant key is a credential in the encrypted vault named exactly after the provider family (openai, anthropic, openrouter, deepseek, moonshot, or gemini) with provider set to the same value and secret { "value": "<api key>" }:

curl -X POST http://localhost:4100/api/v1/credentials \
  -H 'content-type: application/json' \
  -d '{ "name": "openai", "provider": "openai", "secret": { "value": "sk-…" } }'

Behavior:

• Live calls for that tenant use the tenant's key; the run's trace records keySource: "tenant" (vs "platform") on model.requested, and the route explanation says so.
• Tenants without a key use the platform env key, unchanged.
• A tenant key takes a family live even when the platform has no env key for it; PUNK_PROVIDER=mock still forces mock for everyone.
• Resolution is cached for 60 seconds; storing or deleting a key through the API takes effect immediately.
• Keys are AES-256-GCM encrypted at rest and never returned by the API. Manage them in the dashboard under Governance → Provider keys (one-time entry, masked after).

Provider Failover

When the primary provider for a model hard-fails, Punk transparently fails over to a backup instead of erroring to the customer. The request follows a failover chain built per request:

1. Primary: the provider the registry picks for the requested model (honoring the tenant's BYOK key).
2. Cross-family backup: for OpenAI/Anthropic families, a configured provider in the other family serves a mapped sibling model. Specialist and OpenRouter model ids can still fall back to the mock backstop when policy allows, but Punk does not silently translate a DeepSeek/Kimi slug to a different commercial provider unless the route records that substitution.
3. Mock backstop: the deterministic mock, appended last when PUNK_FAILOVER_TO_MOCK allows it, so a request never dies for lack of a provider.

The route still reports live; the failover is surfaced in the run's route explanation (failover.attempts + failover.servedBy), a model.failover trace event, and the dashboard's Overview/Runs/run-detail failover badges.

Cross-family model map

A backup serves the equivalent model in the other family, not the requested model name (which the backup wouldn't recognize):

Unmapped models fall back to the family default sibling (claude-sonnet-4-6 / gpt-4o). The served model determines cost (estimateCost runs on the model that actually answered).

What triggers failover

A non-retriable error, or an exhausted chain, finalizes the run as failed (with the run's run.completed event and route explanation intact, so the run is never abandoned). When PUNK_FAILOVER_TO_MOCK=false and all real providers fail, the last real provider's error is returned.

Mock backstop gating

Silently returning simulated content in production can be worse than a clean error, so the mock backstop is a deliberate, gated choice. PUNK_FAILOVER_TO_MOCK defaults to true only when no real provider is configured for the request (open dev); once a platform key or tenant BYOK key exists it defaults to false. Set it explicitly to opt back in.

Streaming boundary

Failover for streaming applies only before the first byte reaches the client: Punk establishes the stream across the chain (pulling the first chunk), and if that errors retriably it advances to the next attempt. Once the first chunk is in hand, Punk commits to that provider; a later mid-stream error finalizes the run failed (you can't un-send bytes).

Auth Modes

Open Dev Mode

When PUNK_API_KEY is unset:

• Headerless requests are accepted.
• Requests resolve to default tenant.
• Requests are admin.
• Private web fetches are allowed for local demo/fixture use.

Do not expose open dev mode publicly.

Protected Mode

When PUNK_API_KEY is set:

• Protected routes require bearer auth.
• The bootstrap token is admin.
• You can create tenant API keys through /api/v1/keys.
• Private web fetches are blocked unless PUNK_ALLOW_PRIVATE_WEB_FETCH=true.

Login Mode

Login mode turns on automatically once any user exists, or when PUNK_REQUIRE_LOGIN=true:

• Private web fetches are blocked unless PUNK_ALLOW_PRIVATE_WEB_FETCH=true.
• Headerless and cookieless /api/v1/* requests return 401.
• The dashboard at / serves the login page until a punk_session cookie resolves (the page is always available at /login).
• /docs, /health, the marketing splash, and /v1/* gateway endpoints keep their existing rules; gateway traffic stays API-key territory.
• Bearer tokens keep working unchanged; sessions and keys coexist.

Bootstrap the first admin from the environment (idempotent on every boot; it never resets a changed password):

Sessions are HttpOnly cookies (SameSite=Lax, 30 days, Secure over HTTPS); the session token is shown once and stored only as a hash. Login attempts are rate-limited to 10 per minute per IP. Users, roles, and password resets are managed in the dashboard under Governance → Users, or via /api/v1/users (admin only).

Tenant API Keys

API keys can be:

• Admin or non-admin.
• observe or optimize.
• Pinned to an app id.
• Revoked.

The full token is returned once and stored only as a hash.

Tenant Settings

Settings are managed through /api/v1/settings.

Tripwires, streaming DLP, memory quarantine, and cross-tenant learning are all opt-in and default-off, so existing behavior is unchanged until you turn them on. See Governance for the governance items.

Database Choice

Use SQLite for:

• Local development.
• Demos.
• Single-process prototypes.

Use Postgres for:

• Deployed environments.
• Separate worker processes.
• Multi-instance API.
• More reliable job processing.

Policy Directory

Default policies are read from policies/.

Policy files:

• Must end in .yaml or .yml.
• Are loaded in sorted order.
• Invalid files are skipped with a warning.
• Can be hot-reloaded by the governance runtime when invoked.