Configuration reference

The gateway is configured entirely through environment variables — there is no config file and no command-line flags on the server binary. It reads them once at boot; changing one means restarting the process.

Generated, not hand-written

The table below is emitted by make -C gateway docs directly from the gateway’s config manifest (gateway/internal/config/reference.go). A CI check (make -C gateway check) fails if the gateway starts reading a new variable that isn’t documented here, so this reference can’t silently fall behind the code.

The two FARCASTER_OIDC_* required variables have no default — the gateway refuses to start without them (see Install and Auth & multi-tenancy). Everything else has a safe default or a dev-only fallback; the Deployment, Postgres, and KMS & secrets pages cover the production-relevant ones in context.

Server

Variable	Required	Default	Description
FARCASTER_ADDR	No	:8080	TCP address the gateway’s HTTP server listens on.

Storage

Variable	Required	Default	Description
FARCASTER_DATABASE_URL or DATABASE_URL	No	—	PostgreSQL connection string (pgx DSN). When unset, the gateway falls back to a non-durable in-memory store — development only; all state is lost on restart. DATABASE_URL is honored as a fallback. Migrations are applied automatically on boot.

Authentication (OIDC)

Variable	Required	Default	Description
FARCASTER_OIDC_ISSUER	Yes	—	OIDC issuer base URL used for provider discovery. The gateway refuses to start without it — there is no unauthenticated path to bring it up.
FARCASTER_OIDC_AUDIENCE	Yes	—	Expected value of the JWT aud claim. The gateway refuses to start without it.
FARCASTER_OIDC_TENANT_CLAIM	No	""	JWT claim carrying the tenant/client identifier. Provider-specific; leave empty to disable tenant extraction.
FARCASTER_OIDC_USER_CLAIM	No	sub	JWT claim carrying the acting user’s subject. sub is the OIDC standard.
FARCASTER_OIDC_SCOPE_CLAIM	No	scope	JWT claim carrying the token’s OAuth scopes (a space-separated string or a JSON array). Leave empty to disable scope extraction. scp is common on Microsoft/Auth0.

Secrets & KMS

Variable	Required	Default	Description
FARCASTER_KMS_KEY	No	—	Hex-encoded 32-byte (64 hex chars) master key for the local KMS provider, which envelope-encrypts stored credentials. When unset, a random ephemeral key is generated that does not survive a restart — never run production without setting it.

Secrets (FARCASTER_DATABASE_URL, FARCASTER_KMS_KEY, and any provider credentials) should come from your platform’s secret store or an injected environment, never from a committed file — see KMS & secrets.