Flank Environment
This page is the canonical list of environment variables the flank app reads at runtime. Flank is the visual workflow editor for the brain-owned workflow engine; its server functions call brain over HTTP, so its essential config is the brain API target plus Clerk auth.
Per the deployment-env standard, the service stage variable
is FLANK_STAGE and must be one of production, staging, sandbox, or development.
NODE_ENV is reserved for the Node runtime mode and must not be used as the app stage.
Variables
| Variable | Required | Default | Source | Purpose |
|---|---|---|---|---|
BRAIN_API_URL | Yes | — | apps/flank/app/lib/brain-http-client.ts | Base URL of brain’s HTTP workflow API. All workflow/execution operations go here. Server functions throw if unset. |
FLANK_STAGE | Yes (prod/staging) | development | apps/flank/server/runtime/stage.ts | Service app stage. Drives logging, feature flags, telemetry tags. |
PORT / FLANK_PORT | No | 3100 | apps/flank/server/entry.ts | HTTP port for the TanStack Start app. PORT wins on Railway; FLANK_PORT is the local default. |
CLERK_SECRET_KEY | Yes (prod/staging) | — | apps/flank/app/lib/auth.ts | Clerk backend secret. Used by requireAuth() on every server function and to mint the per-request session JWT forwarded to brain. |
CLERK_PUBLISHABLE_KEY / VITE_CLERK_PUBLISHABLE_KEY | Yes (prod/staging) | — | apps/flank/app/lib/auth.ts | Clerk client/publishable key. Used by createClerkClient; the VITE_-prefixed form is exposed to the browser. |
FLANK_AUTH_BYPASS_UUID | No | unset | apps/flank/app/lib/auth.ts | When set, requireAuth() returns this UUID without calling Clerk. Local development only — never set in production. Note: with auth bypassed no Clerk JWT is minted, so brain calls are unauthenticated. |
NODE_ENV | No | production (build) | Vite/TanStack Start | Node runtime mode only. Do not use as service stage. |
How flank authenticates to brain
Flank does not hold a brain API key. For each request, mintBrainToken()
(apps/flank/app/lib/auth.ts) mints a fresh Clerk session JWT and sends it as a
Bearer token to brain (the same shape fennec produces). Brain validates it via Clerk and
gates workflow operations behind the ADMIN role. A valid Clerk session is therefore
required for flank to read or write any workflow data.
Legacy / being retired
These variables belonged to the old model where flank ran its own engine and stored data
in sirloin via gRPC. They are superseded by BRAIN_API_URL and brain’s HTTP API. They may
still appear in apps/flank/.env.example and in code paths that have not been deleted yet,
but new deployments should not depend on them. TODO(@law): remove these once the legacy
gRPC/seed-sync wiring is gone.
| Variable | Former purpose |
|---|---|
SIRLOIN_GRPC_URL | Sirloin gRPC address for the old FlankStorageService storage client and seed-sync. |
FLANK_SERVICE_TOKEN | Service-to-service token flank sent on FlankResolveSecrets gRPC calls. |
FLANK_ENCRYPTION_KEY | AES-256 master key sirloin used to encrypt flank secret values at rest. |
FLANK_SECRET_* | Env-var fallback for adapter secret references ({{secret:name}}) under the old secret store. |
FLANK_R2_PUBLIC_URL / FLANK_R2_SIGNING_KEY | CDN base URL and signing key for the old data:media / data:character flank nodes. |
Stage-by-stage requirements
| Stage | Must set | May set |
|---|---|---|
development (local) | BRAIN_API_URL | FLANK_AUTH_BYPASS_UUID, FLANK_PORT, Clerk keys |
sandbox | BRAIN_API_URL, Clerk keys, FLANK_STAGE | — |
staging | All Yes rows above | — |
production | All Yes rows above | — |
Source of truth
Definitive references when this table drifts:
apps/flank/.env.example— the maintained example envapps/flank/app/lib/brain-http-client.ts—BRAIN_API_URL, request wiringapps/flank/app/lib/auth.ts— Clerk + bypass UUID + brain token mintingapps/flank/server/entry.ts— port wiring, startup orderapps/flank/railway.json— Railway build/deploy config (Dockerfile builder, healthcheck path/sign-in, single replica inus-east4-eqdc4a). Note: the full set of environment variables for each Railway environment is configured in the Railway dashboard, not in this file. TODO(@law): mirror the Railway env list here once exported.
When adding a new variable, update both the table here and apps/flank/CLAUDE.md.