Keel Cloud configuration

keel-cloud is configured entirely through environment variables.

Core

Variable	Default	Description
`KEEL_DATABASE_URL`	—	Required. PostgreSQL URL, e.g. `postgres://keel:keel@localhost:5432/keel?sslmode=disable`. `DATABASE_URL` is read when unset.
`KEEL_ADDR`	`:8080`	Listen address.
`KEEL_BASE_URL`	`http://localhost:8080`	Public origin used for invitations, OAuth discovery, MCP token audience, and Secure cookies. HTTPS is required except on loopback. No path, query, fragment, or embedded credentials. Trailing slashes are stripped. See MCP.
`KEEL_DATA_DIR`	`./keel-data`	Working directory for repository clones and run workspaces (`runs/<run-id>`), and the generated encryption key when none is configured. Must be a host path when `keel-cloud` runs in a container — see self-hosting.
`KEEL_ENCRYPTION_KEY`	generated	64 hexadecimal characters (32 bytes) — the AES-256 key for variable values, repository tokens, and secret outputs at rest. `openssl rand -hex 32` produces one. When unset, a key is generated into `KEEL_DATA_DIR/encryption.key` and a warning is logged.

GitHub App

All optional. Setting KEEL_GITHUB_APP_ID enables the integration and makes a private key and a webhook secret mandatory.

Variable	Description
`KEEL_GITHUB_APP_ID`	Numeric App ID.
`KEEL_GITHUB_APP_SLUG`	The app’s URL slug; used to build the install link.
`KEEL_GITHUB_PRIVATE_KEY`	The app’s private key as inline PEM.
`KEEL_GITHUB_PRIVATE_KEY_FILE`	Path to the `.pem` file; used when the inline key is unset.
`KEEL_GITHUB_WEBHOOK_SECRET`	The webhook secret configured on the app.

See GitHub App for the setup.

Host requirements

PostgreSQL 13 or newer, reachable at KEEL_DATABASE_URL. Migrations run at startup.
git on the PATH. Startup fails without it.
The Docker CLI on the PATH and a reachable daemon. Missing Docker does not stop startup; deploys fail with a clear message until it is available.

Endpoints worth knowing

Path	Purpose
`GET /healthz`	`ok` when the database responds; 503 otherwise.
`/mcp`	OAuth-protected Streamable HTTP MCP endpoint.
`/.well-known/oauth-protected-resource/mcp`	MCP authorization discovery.
`/.well-known/oauth-authorization-server`	OAuth server metadata.
`/account/agents`	View and revoke your agent connections.
`POST /webhooks/github`	GitHub App deliveries; HMAC-verified.
`GET /orgs/{org}/repos/{repo}/runs/{id}/events`	Server-sent events for a run’s live log. Disable proxy buffering here.

Logging

Structured key=value lines on standard error at info level. Startup logs the listen address, base URL, and version; the GitHub App logs its App ID when enabled.

keel.yaml

Runtime

Keel Cloud configuration

Core

GitHub App

Host requirements

Endpoints worth knowing

Logging

​Core

​GitHub App

​Host requirements

​Endpoints worth knowing

​Logging

Core

GitHub App

Host requirements

Endpoints worth knowing

Logging