Skip to content
Beef Docs

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

Section titled “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 — 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 Yes None apps/flank/app/lib/auth.ts, apps/flank/app/routes/__root.tsx Clerk publishable key for the server client and browser provider. The root route passes it to the browser.
SIRLOIN_GRPC_URL Conditional: character recipe/family administration, seed commands, and playground character search — (http://localhost:50051 in .env.example) apps/flank/app/lib/grpc-client.ts, apps/flank/app/lib/strip-client.ts, apps/flank/scripts/seed-character-recipes.ts, apps/flank/scripts/seed-character-recipe-families.ts Sirloin gRPC endpoint used to manage and seed character recipes and recipe families, and to search characters from the playground.
FLANK_CHARACTER_RECIPE_SEED_ON_DEPLOY No unset apps/flank/scripts/predeploy-seed.sh Enables the pre-deploy combined fixture seed only when exactly true. Leave unset in preview and production.
CHARACTER_RECIPE_SEED_REPLACE No true apps/flank/scripts/seed-character-recipes.ts Controls whether an explicit combined seed replaces divergent published recipe fixtures. Treat as a one-shot operator input, not a permanent runtime setting.
CHARACTER_RECIPE_FAMILY_SEED_REPLACE No false standalone; inherits CHARACTER_RECIPE_SEED_REPLACE in the combined seed when unset apps/flank/scripts/seed-character-recipe-families.ts Controls whether divergent published family fixtures may be replaced. Keep false for family-only repair unless replacement was reviewed.
FLANK_CHARACTER_RECIPE_SEED_ACTOR_ID No flank:recipe-seed apps/flank/scripts/seed-character-recipes.ts Audit principal recorded for recipe fixture mutations.
FLANK_CHARACTER_RECIPE_FAMILY_SEED_ACTOR_ID No flank:recipe-family-seed apps/flank/scripts/seed-character-recipe-families.ts Audit principal recorded for family fixture mutations.
FLANK_OPENROUTER_API_KEY Conditional: funnel step studio unset apps/flank/app/lib/step-studio/generate.server.ts OpenRouter key provided to the Flank server for custom-step generation. Without it the studio reports that it is not configured.
FLANK_STEP_STUDIO_MODEL No anthropic/claude-sonnet-5.5 apps/flank/app/lib/step-studio/generate.server.ts OpenRouter model ID for step generation.
NODE_ENV No production (build) Vite/TanStack Start Node runtime mode only. Do not use as service stage.

How flank authenticates to brain

Section titled “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 requires ADMIN for workflow authoring and administration. Published discovery, execution, and polling allow CREATOR and above only where the controllers declare that access. See apps/brain/src/modules/domain/workflow/controllers/. A valid Clerk session is required locally and in deployed environments.

Legacy / removed

Section titled “Legacy / removed”

FLANK_AUTH_BYPASS_UUID is no longer implemented. It does not bypass Clerk. VITE_CLERK_PUBLISHABLE_KEY is also not read; use CLERK_PUBLISHABLE_KEY.

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. SIRLOIN_GRPC_URL remains active and is documented in the main table above. The rest are listed only so operators can clean stale values out of deployed environments.

Variable Former purpose
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

Section titled “Stage-by-stage requirements”
Stage Must set May set
development (local) BRAIN_API_URL, Clerk keys SIRLOIN_GRPC_URL for recipe/family administration, seeds, or character search; FLANK_PORT, one-shot seed variables
sandbox BRAIN_API_URL, Clerk keys, FLANK_STAGE SIRLOIN_GRPC_URL for recipe/family administration, seeds, or character search
staging All Yes rows above SIRLOIN_GRPC_URL for recipe/family administration, seeds, or character search
production All Yes rows above SIRLOIN_GRPC_URL for recipe/family administration, seeds, or character search

Source of truth

Section titled “Source of truth”

Definitive references when this table drifts:

  • apps/flank/.env.example — the maintained example env
  • apps/flank/app/lib/brain-http-client.ts — BRAIN_API_URL, request wiring
  • apps/flank/app/lib/auth.ts: Clerk authentication and brain token minting
  • apps/flank/server/entry.ts — port wiring, startup order
  • apps/flank/railway.json — Railway build/deploy config (Dockerfile builder, healthcheck path /sign-in, single replica in us-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 variable, update this table and the value-free apps/flank/.env.example. apps/flank/CLAUDE.md imports the shared guide and does not duplicate this table.