Configuration

Quayside reads all its settings from environment variables (or a .env file in services/api/). This page lists every variable.

Format

All variables use the QUAYSIDE_ prefix. Booleans are case-insensitive (true/false/1/0). Secrets use pydantic.SecretStr — they don’t appear in logs or repr output.

Postgres

Var	Default	Notes
`QUAYSIDE_DATABASE_URL`	—	Required at runtime. `postgres://user:pass@host:port/db`
`QUAYSIDE_TEST_DATABASE_URL`	falls back to `QUAYSIDE_DATABASE_URL`	Used by the test fixture only

Logging

Var	Default	Notes
`QUAYSIDE_LOG_LEVEL`	`info`	Forwarded to FastAPI / uvicorn

Anthropic upstream

Quayside’s proxy talks to Anthropic when configured. Leave the key unset and the proxy uses a deterministic MockUpstream for development.

Var	Default	Notes
`QUAYSIDE_ANTHROPIC_API_KEY`	unset	Secret. Set to enable real Anthropic forwarding.
`QUAYSIDE_ANTHROPIC_BASE_URL`	`https://api.anthropic.com`	Override for staging or a Bedrock-style sidecar
`QUAYSIDE_ANTHROPIC_VERSION`	`2023-06-01`	Sent as the `anthropic-version` header
`QUAYSIDE_ANTHROPIC_TIMEOUT_S`	`60.0`	Whole-request httpx timeout

Auth (JWT)

Var	Default	Notes
`QUAYSIDE_JWT_SECRET`	dev-only fallback when `DEV_MODE=true`	Secret. Required when `DEV_MODE=false`. HS256 signing key.
`QUAYSIDE_JWT_ALGORITHM`	`HS256`	Only `HS256` supported in v1
`QUAYSIDE_JWT_TTL_SECONDS`	`3600`	Default token lifetime
`QUAYSIDE_JWT_ISSUER`	`quayside`	`iss` claim
`QUAYSIDE_DEV_MODE`	`true`	When true, enables the `/auth/dev/mint-token` endpoint AND the X-Quayside-* header fallback at the proxy. Set to `false` in production.

Production safety

Two things you absolutely must set differently in production:

QUAYSIDE_DEV_MODE=false
QUAYSIDE_JWT_SECRET=<at least 32 random bytes>

The first disables the easy-mint endpoint. The second forces explicit secret configuration; the dev fallback secret is a publicly-known string in source.

A complete `.env` example

For local development:

QUAYSIDE_DATABASE_URL=postgres://quayside:quayside@localhost:5432/quayside
QUAYSIDE_TEST_DATABASE_URL=postgres://quayside:quayside@localhost:5433/quayside_test
QUAYSIDE_LOG_LEVEL=info
QUAYSIDE_DEV_MODE=true
# QUAYSIDE_ANTHROPIC_API_KEY=sk-ant-...

For production:

QUAYSIDE_DATABASE_URL=postgres://...your-managed-postgres-dsn...
QUAYSIDE_LOG_LEVEL=info
QUAYSIDE_DEV_MODE=false
QUAYSIDE_JWT_SECRET=...32-bytes-of-randomness...
QUAYSIDE_ANTHROPIC_API_KEY=sk-ant-...

Frontend

The dashboard reads one var:

Var	Default	Notes
`NEXT_PUBLIC_QUAYSIDE_API_URL`	empty	If set, the dashboard’s API client uses this as the base URL. Empty means same-origin (relies on the Next.js `/api/v1/*` rewrite in dev).

CLI

Var	Default	Notes
`QUAYSIDE_CLI_HOME`	`~/.config/quayside/`	Where to store the token cache
`QUAYSIDE_URL`	`http://localhost:8000`	Default server when no flag and no cached URL

Migration runner

The quayside-migrate and quayside-seed CLIs read QUAYSIDE_DATABASE_URL if no --database-url is passed. They also respect:

Var	Notes
`QUAYSIDE_ENV`	If set to `prod`, refuses `--reset` unless `--i-know-this-drops-everything` is also passed.
`QUAYSIDE_MIGRATIONS_DIR`	Override where to find `*.sql` files. Mostly for tests.