//DOCS Configuration

Environment variables, auth modes, database choices, and settings.
GitHub Docs

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: deterministic mock simulator when OPENAI_API_KEY is absent.
  • Auth: open dev mode when PUNK_API_KEY is absent.
  • Worker: embedded in the API process.
  • Learning tick: every 10 seconds.
  • SOM runtime: built-in TypeScript compiler unless PLASMATE_URL is set.
  • Governance: embedded policy engine unless MESHGUARD_URL is set.

Environment Variables

VariableDefaultPurpose
PUNK_PORT4100HTTP port.
PUNK_API_KEYunsetBootstrap bearer token. When set, /api/ and /v1/ require auth.
PUNK_DATABASE_URLunsetPostgres/Neon-compatible database URL. Overrides SQLite.
PUNK_DB_PATHdata/punk.dbSQLite database path.
PUNK_PROVIDERinferredmock or openai; forces provider choice.
OPENAI_API_KEYunsetEnables live OpenAI-compatible pass-through.
OPENAI_BASE_URLOpenAI defaultOptional compatible provider base URL.
PLASMATE_URLunsetAWP WebSocket endpoint for Punk's Plasmate-compatible semantic web adapter.
MESHGUARD_URLunsetMeshGuard-compatible governance control plane URL.
MESHGUARD_API_KEYunsetOptional token for governance bridge.
PUNK_POLICIES_DIRpoliciesDirectory containing policy YAML.
PUNK_AUTO_PROMOTEfalseAllows hands-free promotion for side-effect-free artifacts that pass gates.
PUNK_LEARN_INTERVAL_MS10000Learning tick enqueue cadence.
PUNK_WORKER_POLL_MS500Embedded/standalone worker poll interval.
PUNK_RETENTION_DAYS90Retention sweep window.
PUNK_RATE_LIMIT_RPM300/api/v1/* requests per caller per minute; 0 disables.
PUNK_CHAT_RATE_LIMIT_RPM600/v1/chat/completions requests per caller per minute; 0 disables.
PUNK_ALLOW_PRIVATE_WEB_FETCHfalse when auth enabledAllows web fetch to private/loopback addresses in authenticated deployments.
PUNK_ALLOW_PRIVATE_WEBHOOKSfalseAllows webhook URLs to private addresses. Always off unless explicitly true.

Provider Modes

SetupBehavior
No OPENAI_API_KEYDeterministic mock provider, fully offline.
OPENAI_API_KEY setLive OpenAI-compatible pass-through.
PUNK_PROVIDER=mockForce mock even if API key is present.
PUNK_PROVIDER=openai + keyForce live provider.

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

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.

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.

SettingPurpose
retention_daysTenant retention window.
redactionRedact SDK tool/side-effect payloads before trace append.
webhook_urlPublic webhook destination.
webhook_secretHMAC/signing secret; not returned by GET.
approval_exception_ttl_hoursDuration for approved policy exceptions.
canary_enabledPromotion enters canary rollout rather than full traffic.

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.