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. |
Postgres 16 with pgvector. Without the extension the server starts anyway, logs one line and silently loses episodic memory — see install.
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 |
An admin cannot save an identity provider at all — 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.