Self-hosting

Configuration

Configuration is entirely environment variables. There is no config file, and no flag that reads one.

This page is the prose. The flat alphabetical list is generated from the source tree — operators search for a variable name, so that page is a lookup, and this one explains what things mean and what breaks without them.

Database

Variable	Unset means
`GARBOARD_DB_URL`	No server. This is required.
`GARBOARD_DB_PASSWORD`	`GARBOARD_DB_URL` is used exactly as given, which is the ordinary case.

Set GARBOARD_DB_PASSWORD when your platform rotates the database password — a managed instance whose secret is rotated on a schedule. Put everything that does not rotate in GARBOARD_DB_URL (host, port, database, user, sslmode) and let the password arrive separately; the server injects it, percent-encoding it correctly, and it overrides any password still present in the URL. Nothing is stored, so a rotation takes effect on the next restart with no hook to maintain.

Postgres 16 with pgvector. Without the extension the server starts anyway, logs one line and silently loses episodic memory — see install.

Cost estimates

Variable	Unset means
`GARBOARD_PRICING`	The built-in price table, and no outbound call. This is the default.

Set it to aws to price RDS and ElastiCache from AWS’s own published price list, per region and per engine, instead of the built-in table’s us-east-1 approximations.

It makes outbound HTTPS calls to pricing.us-east-1.amazonaws.com — public JSON, no AWS credentials — and caches each region for a day. A cold cache never blocks a review: that review uses the built-in table and the next one has real prices.

garboard gate ignores this variable entirely. The gate is offline by invariant and runs inside your CI; it always uses the built-in table.

Identity of the instance

Variable	Unset means
`GARBOARD_BASE_URL`	Your git host cannot call you. Must be publicly reachable.
`GARBOARD_UI_URL`	Links back into the UI are wrong or absent.

The git host

Variable	Unset means
`GARBOARD_GIT_PROVIDER`	Defaults to GitHub. Set `gitlab` for GitLab.
`GARBOARD_GITHUB_APP_ID`	`/webhook` returns 503 — unconfigured.
`GARBOARD_GITHUB_PRIVATE_KEY_FILE`	Same.
`GARBOARD_WEBHOOK_SECRET`	Deliveries fail signature verification.
`GARBOARD_GITLAB_TOKEN` / `_URL` / `_WEBHOOK_SECRET` / `_GROUP`	GitLab equivalents. The webhook secret is fail-closed: unset refuses every delivery, with a warning at startup.

Keys you must back up

Variable	Unset means
`GARBOARD_SECRET_KEY`	No one can save an identity provider at all, not even an owner — there is nothing to seal the client secret with. Per-organisation SSO is unavailable.
`GARBOARD_KMS_KEY_ID`	Use an external KMS key instead of the local envelope key.
`GARBOARD_RECEIPT_KEY`	Receipts are written unsigned, and every surface says so.
`GARBOARD_RECEIPT_RETIRED_KEYS`	Receipts signed with a rotated-out key stop verifying.

Losing the first two makes sealed data permanently unopenable. See backup and restore.

Authentication

Variable	Unset means
`GARBOARD_AUTH`	No auth required. Set `1` to require it.
`GARBOARD_TOKEN`	No service token. Setting one gates the API surface, including `/metrics`.
`GARBOARD_OIDC_ISSUER` / `_CLIENT_ID` / `_CLIENT_SECRET` / `_REDIRECT_URL`	No instance-level SSO.
`GARBOARD_SSO_ALLOWED_DOMAINS`	SSO admits any identity your provider asserts. Set this.
`GARBOARD_SIGNUP_DISABLED`	Self-service signup is open. Set `1` for invite-only.

Outbound, and how to switch it off

Variable	Unset means
`ANTHROPIC_API_KEY`	No prose, no fixes — and a fully working gate. Not a degraded mode.
`GARBOARD_EMBEDDER`	The offline `hash` embedder. No outbound call.
`GARBOARD_EMBEDDER_MODEL` / `_DIM` / `_URL`	Only relevant with a hosted embedder. `_DIM` must match the model’s output width.
`GARBOARD_SCHEMA_DIR`	The default pinned provider CRD cache location.
`GARBOARD_SLACK_WEBHOOK`	The notifier is a no-op. Break-glass expiry reminders are off entirely.

These are the only outbound paths, and each is off or offline by default. See data flow.

Retention

Variable	Unset means
`GARBOARD_AUDIT_RETENTION_DAYS`	Keep the audit log forever. Zero, negative and non-numeric mean the same — the safe direction.

Not for you

Some variables the binary reads are not configuration: test switches and hosted-mode flags. They are deliberately absent from the generated reference, and the classification that withholds them fails the build if someone adds a variable without deciding which side it is on. If you found one by reading a process listing, it is not a supported knob.