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:
bun run setup:local # create .env.local from the tracked template, mode 0600, with a generated auth secretbun run check:local # confirm the configured PostgreSQL and S3-compatible endpoints are reachablesetup: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.
API process variables
Section titled “API process variables”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.
What the public origin decides
Section titled “What the public origin decides”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:
- the public origin’s host and port,
- every entry in
ARTIFLOW_ALLOWED_HOSTS, - the loopback API authority (
127.0.0.1:8787by default) — outside production only.
Login availability
Section titled “Login availability”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.
Tooling and deployment variables
Section titled “Tooling and deployment variables”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.
Secret handling
Section titled “Secret handling”.env.localis created mode0600and is not committed. The tracked template is the only committed shape.- The production env file is
.env.prodby default: keep it mode0600and out of version control. - Generate
ARTIFLOW_AUTH_SECRETwithopenssl rand -hex 32(or letbun run setup:localgenerate 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.
Deliberately not configurable
Section titled “Deliberately not configurable”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
/docsand/mcppaths.