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 / removed
These variables belonged to the old model where flank ran its own engine and stored data
in sirloin via gRPC. That wiring has been deleted (engine, gRPC server, seed-sync, and the
sirloin storage client are gone from apps/flank), so the retired paths no longer read
them. Exception: SIRLOIN_GRPC_URL is still read by character recipe administration
(CharacterRecipeService) and playground character search (StripService), not by
any removed path. The rest are listed only so operators can clean stale values out of
deployed environments.
| Variable | Former purpose |
|---|---|
SIRLOIN_GRPC_URL | Still read — used for character recipe administration and playground character search, not the removed storage/execution path. |
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.