Skip to content

Configuration

The API process reads its configuration from the environment once, at startup, and validates every value before it opens a listener. A missing or invalid value stops the process with a message naming the variable, never echoing the value it rejected.

Two repository scripts manage that file locally:

Terminal window
bun run setup:local # create .env.local from the tracked template, mode 0600, with a generated auth secret
bun run check:local # confirm the configured PostgreSQL and S3-compatible endpoints are reachable

setup:local preserves an existing .env.local, refuses a secret shorter than 32 characters instead of silently replacing it, and never prints a secret. Neither script provisions PostgreSQL or object storage: the operator supplies both.

These are read by apps/api/src (config.ts and the scripts it shares).

Variable Required Default Rule
NODE_ENV no development development, production or test
DATABASE_URL yes — postgres:// or postgresql:// connection string
ARTIFLOW_AUTH_SECRET yes — At least 32 characters; keep it stable across restarts or every session is invalidated
ARTIFLOW_S3_ENDPOINT yes — Absolute http(s) URL of the S3-compatible endpoint
ARTIFLOW_S3_BUCKET yes — Lowercase [a-z0-9.-], 3–63 characters, starting and ending alphanumeric; must already exist and stay private
ARTIFLOW_S3_ACCESS_KEY_ID yes — Access key for the private bucket
ARTIFLOW_S3_SECRET_ACCESS_KEY yes — Secret for the same key
ARTIFLOW_S3_REGION no us-east-1 Any region string your provider expects (auto on R2)
ARTIFLOW_S3_FORCE_PATH_STYLE no derived 1 (path style), 0 (virtual-host) or unset: path style when the endpoint host is loopback, virtual-host otherwise
ARTIFLOW_PUBLIC_ORIGIN no http://127.0.0.1:5173 Absolute http(s) origin with no path, query or fragment
ARTIFLOW_API_HOST no 127.0.0.1 127.0.0.1 or 0.0.0.0 only
ARTIFLOW_API_PORT no 8787 Integer 1–65535
ARTIFLOW_INTERNAL_ORIGIN no http://127.0.0.1:<port> Bare http(s) origin the process uses to fetch its own JWKS; derived on loopback even when the API binds 0.0.0.0, so set it behind a sidecar or remapped port
ARTIFLOW_ALLOWED_HOSTS no empty Comma-separated host[:port] authorities, no scheme, path or wildcard
ARTIFLOW_DEMO_AUTH no off 1 enables the local demo login; startup fails unless NODE_ENV=development and the public origin is loopback
ARTIFLOW_AUTH_GITHUB_CLIENT_ID / ARTIFLOW_AUTH_GITHUB_CLIENT_SECRET no not configured Both or neither: a half-set pair fails startup
ARTIFLOW_AUTH_GOOGLE_CLIENT_ID / ARTIFLOW_AUTH_GOOGLE_CLIENT_SECRET no not configured Both or neither: a half-set pair fails startup

The four required storage values plus DATABASE_URL are reported together when missing, so one run lists every gap. Errors mention names only: no password, bucket key or credential ever reaches a log or a response body.

ARTIFLOW_PUBLIC_ORIGIN is the single source for every absolute URL the instance publishes:

Derived value Form
OAuth issuer <origin>/api/auth
MCP resource <origin>/mcp
API v1 resource <origin>/api/v1
Public link URL <origin>/share/<token>
Well-known documents <origin>/.well-known/…
Cookie-mutation guard The exact Origin every dashboard mutation must carry

Changing it re-points discovery, the JWT issuer and every resource identifier at once. Clients registered and tokens issued under the previous origin stop matching, so treat a change of origin as a deployment step: re-register clients and re-authenticate them afterwards. Use a bare origin — a value with a path or query is rejected at startup rather than half-working later.

ARTIFLOW_ALLOWED_HOSTS exists for the one case the derived set cannot cover: a proxy that sends a Host header the public origin does not match. The MCP transport compares the raw Host header by string equality, and the trusted set is:

  1. the public origin’s host and port,
  2. every entry in ARTIFLOW_ALLOWED_HOSTS,
  3. the loopback API authority (127.0.0.1:8787 by default) — outside production only.

Who can sign in is decided by NODE_ENV, not by a build flag:

Environment Email and password
production Always available
development with ARTIFLOW_DEMO_AUTH=1 and a loopback public origin Available
Anything else Not available

Social providers appear only when their pair is configured. The browser reads the live answer from GET /api/auth/capabilities instead of guessing: emailPassword reports login availability, the configured socialProviders are listed, and registration carries account-creation availability separately — false in every profile, independently of whether email/password login is available. Accounts are created only from an operator-issued invitation (bun run user:invite EMAIL), which does not change this flag: the public entry stays closed and the invitation link opens its own fixed-email form.

These are read by repository scripts or the container definitions, not by the API configuration:

Variable Read by Default Purpose
ARTIFLOW_DEV_RUNTIME scripts/dev.mjs bun Runtime for the API in development; node is the declared fallback
ARTIFLOW_API_PROXY_TARGET apps/dashboard/vite.config.ts http://127.0.0.1:8787 API upstream for the Vite dev server proxy
ARTIFLOW_ALLOW_REMOTE_MIGRATE migration script off 1 is required to migrate a non-loopback database; a loopback target needs nothing
ARTIFLOW_PROD_ENV_FILE docker-compose.prod.yml .env.prod Which env file the production stack loads
ARTIFLOW_SITE_ADDRESS docker-compose.prod.yml web service none (required) Public DNS name Caddy serves with TLS; :80 for a smoke test without DNS

The production compose file also sets SITE_ADDRESS and API_UPSTREAM for its own web container, and sets NODE_ENV=production plus ARTIFLOW_API_HOST=0.0.0.0 for the API container. Those three are compose-owned: do not duplicate them in your env file.

The local integration stack (docker-compose.yml, PostgreSQL plus a Garage bucket) ships fixed credentials that are only ever valid on loopback. They are for the repository’s integration tests, not a starting point for a deployment.

  • .env.local is created mode 0600 and is not committed. The tracked template is the only committed shape.
  • The production env file is .env.prod by default: keep it mode 0600 and out of version control.
  • Generate ARTIFLOW_AUTH_SECRET with openssl rand -hex 32 (or let bun run setup:local generate it).
  • A public-link token is not configuration: it is generated per link, shown once, and stored only as a SHA-256 hash. See Share and publish.

The following are fixed in code, so no variable exists for them — do not expect to tune them from the environment:

  • OAuth client registration: dynamic registration is on for public clients, and the API v1 resource is opt-in per client, never auto-linked.
  • Public account creation: sign-up is closed in every profile, and no variable re-enables it. See Install Artiflow for the current sign-in behavior.
  • Rate limits and request/body caps (see Limits).
  • CORS and browser origins: the single trusted origin is ARTIFLOW_PUBLIC_ORIGIN.
  • The /docs and /mcp paths.