Configuration

keelwave is configured entirely through environment variables. There is no config file. Every variable is optional except in practice DB_ADDR, which you almost always need to change from its localhost default.

docker run --rm -p 8080:8080 \
  -e DB_ADDR="postgres://keelwave:secret@db:5432/keelwave?sslmode=require" \
  -e ENV="production" \
  -e PUBLIC_URL="https://keelwave.example.com" \
  -e DASHBOARD_URL="https://keelwave.example.com" \
  -e CORS_ALLOWED_ORIGINS="https://keelwave.example.com" \
  ghcr.io/keelwave/keelwave:latest

Unparseable values fall back to the default rather than failing startup: integer variables fall back if strconv.Atoi fails, and duration variables fall back if time.ParseDuration fails. Durations use Go syntax — 500ms, 30s, 168h.

Server

On SIGINT or SIGTERM the server stops accepting connections, drains in-flight requests, flushes the batch buffers, stops the alerting scheduler and worker, and closes the database pool — all inside the SHUTDOWN_TIMEOUT budget.

Database

keelwave requires TimescaleDB, not plain Postgres. The schema declares hypertables for ai_traces, api_events, infra_metrics, agent_runs, and agent_steps, and migration 000010 creates a continuous aggregate (agent_runs_5m) with a refresh policy that depends on TimescaleDB background workers. Compose uses timescale/timescaledb:latest-pg18.

On startup the pool is created and pinged with a 5-second timeout; if the ping fails the process exits. Set sslmode=require (or stronger) in DB_ADDR when the database is not on the same host.

Migrations are never applied automatically — see Production.

CORS

Values are split on commas and trimmed; empty entries are dropped. Requests carry credentials, so * is rejected — if any entry is * the server logs a fatal error and refuses to start. List explicit origins instead.

Allowed methods are GET, POST, PUT, PATCH, DELETE, OPTIONS; allowed headers are Accept, Authorization, Content-Type, X-API-Key, X-Project-ID, X-Org-ID; preflight responses are cached for 300 seconds.

CORS only matters for cross-origin browser callers. Server-side SDKs and the same-origin dashboard are unaffected.

Rate limiting

Two httprate layers guard /v1/ingest/*: a per-IP limiter before API key authentication, and a per-API-key limiter after it. Both return 429 with a Retry-After header.

Raise both limits together if a busy agent fleet shares one egress IP — otherwise the per-IP limit binds first.

Batch buffer

Hot-path ingest rows (ai_traces, api_events, infra_metrics, agent_steps) are queued in memory and written in bulk with COPY.

Enqueue is non-blocking. When a queue is full the handler responds 503 with Retry-After: 1 instead of stalling — SDKs are expected to retry. Sustained 503s mean the database cannot keep up; increase BATCH_MAX_ROWS or BATCH_QUEUE_DEPTH, or give the database more resources.

Note that a larger queue means more rows held only in memory, so more data can be lost if the process is killed without a graceful shutdown.

Authentication and sessions

The session cookie's Secure flag is set when ENV equals production. Behind TLS, set ENV=production so browsers do not send session cookies over plain HTTP.

Email

Email delivery goes through Resend, and is used for account verification and for the email alert channel.

Without a working RESEND_API_KEY and a real MAIL_FROM, registration verification emails and email alerts will not be delivered.

Alerting

Seed script

make seed (cmd/migrate/seed) reads DB_ADDR plus two of its own variables:

API keys

An API key is kw_ followed by base32 (no padding) of 32 random bytes. Only the SHA-256 hash is stored — the plaintext is returned once at creation and cannot be recovered.

SDKs and any direct ingest client authenticate with a bearer header:

Authorization: Bearer kw_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The key determines the project_id for every ingested row; it is resolved in middleware and never read from the request body.

Two ways to create one:

• make seed — creates a project and prints one plaintext key. Development convenience; the seeded user cannot sign in to the dashboard.
• POST /v1/admin/orgs/{orgID}/projects/{projectID}/keys — requires a verified, signed-in user with the admin role in that organization. Body is {"name": "..."}; the 201 response contains the plaintext under key.

List keys with GET and revoke one with DELETE /v1/admin/orgs/{orgID}/projects/{projectID}/keys/{keyID}. Rotate by creating the replacement, deploying it, then deleting the old key.