Control plane configuration

denv-cp is the control plane: API server, host hub, and orchestrator in one process. It is configured by flags, each of which falls back to an environment variable.

Flags

Flag	Env	Default	Meaning
-addr	DENV_ADDR	:8080	Listen address.
-db	DENV_DB	denv.db	Database: a SQLite file path, or a postgres:// DSN. See below for the assembled form.
-public-url	DENV_PUBLIC_URL	http://localhost:8080	The URL sidecars and cloud-init use to reach this server; also the OAuth callback base and the join-token command.
-denvd-url	DENV_DENVD_URL	<public-url>/denvd	Where cloud-init downloads the sidecar.
-v	—	off	Debug logging (request lines are logged at debug).

Environment variables

Variable	Meaning
DENV_DB	As -db. When unset and DENV_DB_HOST is set, a Postgres DSN is assembled from DENV_DB_HOST, DENV_DB_PORT (5432), DENV_DB_NAME (denv), DENV_DB_USER (denv), DENV_DB_PASSWORD, DENV_DB_SSLMODE (require). The password is redacted in logs.
DENV_TEAM	Name of the first team created on an empty database (default default).
DENV_BOOTSTRAP_KEY	API key to install for that first team. When unset a random dak_… is generated and printed to stderr once. Only consulted when the database has no teams.
DENV_CONSOLE_URL	The console's origin. Enables CORS for it, sets the default post-login return (<console>/app/), the device-flow verification URL (<console>/app/device/), and the GitHub check-run link (<console>/app/deployment/?id=…).
DENV_GITHUB_CLIENT_ID, DENV_GITHUB_CLIENT_SECRET	GitHub OAuth app for console sign-in. Both unset: /auth/github/* answers 503. Callback URL to register: <public-url>/auth/github/callback.
DENV_DEV_LOGIN	1 enables POST /auth/dev-login (sign in by email, no GitHub). Local use only.
DENV_GITHUB_APP_ID, DENV_GITHUB_APP_PRIVATE_KEY	GitHub App for push-to-deploy. The key is PEM text or a file path. Both unset: the app is off, POST /webhooks/github answers 503, /v1/github/* report configured: false.
DENV_GITHUB_WEBHOOK_SECRET	Verifies X-Hub-Signature-256. Unset with the app configured: webhooks are refused (logged as a warning at start).
DENV_GITHUB_API_URL	Override of https://api.github.com (GitHub Enterprise, tests).
DENV_RELEASES_DIR	Directory served by GET /denvd* (default bin; the container image sets /releases).

Database

SQLite is the default and is used by the end-to-end scripts; the file is opened in WAL mode with a 5 s busy timeout. A postgres:// DSN selects Postgres through pgx. The schema is created and migrated on every start.

GitHub App

Permissions and events the app needs:

Setting	Value
Repository permissions	Contents: read, Metadata: read, Checks: write (optional; a 403 is tolerated and no check runs are posted)
Webhook URL	<public-url>/webhooks/github
Webhook events	push, installation
Webhook secret	DENV_GITHUB_WEBHOOK_SECRET

After a user installs the app, the installation appears in GET /v1/github/installations and must be linked to a team with POST /v1/github/installations/{id}/link before pushes deploy. A project's source is github:owner/repo; its compose path defaults to docker-compose.yaml.

CORS

With DENV_CONSOLE_URL set, requests to /v1/* and /auth/* whose Origin is that URL, http://localhost:*, or http://127.0.0.1:* receive Access-Control-Allow-Origin: <origin>, Access-Control-Allow-Headers: Authorization, Content-Type, X-Denv-Team, Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS, Access-Control-Max-Age: 600. OPTIONS requests on those paths return 204. Without DENV_CONSOLE_URL no CORS headers are sent.

Process notes

• OAuth state values and keys approved by the device flow are held in process memory for up to 10 and 15 minutes respectively. Run one instance of denv-cp, or sign-ins and denv login can fail when a second instance receives the follow-up request.
• The bootstrap team and key are created only when the database has no teams; later teams come from GitHub sign-in or POST /v1/teams.
• Shutdown on SIGINT/SIGTERM waits up to 10 s for in-flight requests.

Managed service

The CDK stacks under infra/ run denv-cp on ECS Fargate behind an HTTPS load balancer with a 3600 s idle timeout for sidecar streams, and inject DENV_PUBLIC_URL=https://api.denv.ai, DENV_CONSOLE_URL=https://denv.ai, the database settings, and the DENV_GITHUB_* values from Secrets Manager (denv/github). See infra/README.md in the backend repository.