Configuration Reference

This page is a public-safe summary of operator-facing configuration categories for deployed Keel runtimes. Customers of the hosted api.keelapi.com service typically do not need to configure these directly; this page is intended for teams running Keel in their own environment.

Current configuration areas

• application mode and environment hardening
• database connectivity and migration prerequisites
• runtime auth and project API-key behavior
• provider-key encryption and outbound provider access
• billing and Stripe integration
• job callback secrets and freshness enforcement
• tracing, diagnostics, and observability toggles

Minimum production configuration

This section summarizes the minimum categories operators must understand for a non-dev deployment. It is intentionally not a full environment-variable dump.

Application and database baseline

• APP_ENV must be set to a non-dev value for production behavior
• DATABASE_URL must point at the runtime database, and migrations must be applied before startup

Required non-dev security settings

In non-dev environments, the settings model currently refuses to start unless the following categories are configured:

• dashboard JWT audience for user JWT validation
• provider key encryption: KEEL_PROVIDER_ENC_KEYS or legacy KEEL_PROVIDER_KEY_ENC_KEY
• client API-key HMAC secret: KEEL_CLIENT_KEY_HMAC_SECRET
• job webhook signing secret: KEEL_JOB_WEBHOOK_SECRET

Request freshness is a hardened non-dev default:

• if APP_ENV is non-dev and KEEL_REQUIRE_REQUEST_FRESHNESS is unset, Keel enables request freshness automatically
• if APP_ENV is non-dev and KEEL_REQUIRE_REQUEST_FRESHNESS=false, startup fails closed
• local, dev, and test environments keep the default off unless the operator enables it explicitly

Non-dev startup also hardens some defaults automatically or refuses unsafe settings, including disabling auth debug logging and defaulting KEEL_REJECT_LEGACY_API_KEY_HASHES to true unless explicitly set.

Runtime execution and provider access

Operators should explicitly review:

• proxy-route exposure, controlled by KEEL_PROXY_ROUTES_ENABLED
• platform-wide execution disablement via KEEL_EXECUTION_DISABLED
• provider pricing JSON for any provider or model that must pass pre-dispatch pricing checks
• provider-key encryption key ring material needed to decrypt project-scoped provider credentials at runtime; new writes use the active key, older ciphertext remains decryptable while its key id stays in the ring, and rewrap is opportunistic on use or manual via CLI rather than a scheduled background rotation job

Billing and external integrations

Only configure these categories if the deployment uses the related surfaces:

• user JWT configuration for dashboard and user auth flows
• Stripe secret, webhook secret, and checkout URLs for billing and checkout flows
• CORS and dashboard CSRF allowed origins for deployed operator frontends

Policy configuration

Project policy overrides via PATCH /v1/projects/{id}/policy are a legacy configuration surface. The primary policy configuration surface is POST /v1/policies/, which accepts PolicyDocument objects with condition trees and rule-based actions. Project overrides continue to work and are compiled to equivalent policy rules at runtime.