Skip to content
Beef Docs

Flank Local Development

This page is the fastest path to a running flank dev server. Flank is the visual workflow editor for the brain-owned workflow engine — locally it needs a reachable brain HTTP API to read and write workflows. For the broader service overview see flank; for env var details see flank-env.

Prerequisites

  • Node 22.x (matches .github/workflows/flank.yml’s NODE_VERSION)
  • pnpm 10.26.0 (PNPM_VERSION in CI)
  • A running brain (locally or via Docker) reachable over HTTP

Install

From the repo root:

Terminal window
pnpm install --frozen-lockfile

The flank workspace is apps/flank and is part of the monorepo lockfile.

Configure environment

Terminal window
cd apps/flank
cp .env.example .env

Minimum local-dev .env:

Terminal window
# App stage
FLANK_STAGE=development
FLANK_PORT=3100


# Brain HTTP API — where all workflow/execution data lives
BRAIN_API_URL=http://localhost:3000


# Skip Clerk in dev — DO NOT set this in any deployed env.
# Note: with the bypass on, no Clerk JWT is minted, so brain calls are unauthenticated.
FLANK_AUTH_BYPASS_UUID=00000000-0000-0000-0000-000000000000


# Or, to exercise the real auth path, set the Clerk keys instead of the bypass:
# CLERK_SECRET_KEY=...
# VITE_CLERK_PUBLISHABLE_KEY=...

See flank-env for the full variable list.

Run

Bring up brain (the workflow engine flank edits), then run flank natively:

Terminal window
# from repo root — starts brain and friends
make dev-up-d


# from apps/flank
pnpm dev

pnpm dev starts the Vite/TanStack Start dev server on port 3100. The editor’s server functions call BRAIN_API_URL for every workflow operation (apps/flank/app/lib/brain-http-client.ts).

Useful additional scripts (apps/flank/package.json):

Terminal window
pnpm typecheck   # tsc --noEmit
pnpm lint        # eslint --max-warnings 0
pnpm test        # vitest run
pnpm dev         # Vite/TanStack Start dev server on port 3100

Authoring and testing workflows

Workflows, subworkflows, and executions live in brain — not in flank. Author them in the ReactFlow editor and test them through brain:

  1. Open http://localhost:3100, sign in (or use the bypass UUID).
  2. Build or open a workflow graph; flank saves it to brain as a draft.
  3. Run a sandbox execution to test the draft without publishing, and inspect the per-node trace (status, timing, inputs, outputs, errors) in the execution view.
  4. Publish to freeze a numbered version that external executors may use.

Legacy, being retired. Flank used to ship git-driven seeds/ (adapter and workflow JSON) that runSeedSync upserted into sirloin storage on boot, plus scripts like exec:workflow, provision:secrets, export:config, and validate:seeds. That model is superseded by brain owning workflow data. Where those scripts/paths still exist they are transitional. TODO(@law): remove the seed-sync wiring and stale scripts once nothing depends on them.

Pre-push checklist

Run all three before opening a PR — CI will block otherwise:

Terminal window
pnpm typecheck && pnpm lint && pnpm test

Common gotchas

  • Port 3100, not 3000 — 3000 is brain’s local default; flank uses 3100 to avoid the collision.
  • BRAIN_API_URL must be reachable — if brain is down, the editor cannot list, load, save, or execute workflows.
  • Auth bypass disables the brain JWT — FLANK_AUTH_BYPASS_UUID skips Clerk, so no bearer token is minted; brain must accept unauthenticated calls in that local setup.
  • Server functions must be imported by a route, otherwise TanStack Start tree-shakes them in production. Dev mode silently masks this.
  • Compound node types (core:trigger) split into {type, kind} at the serialization boundary in app/lib/graph-serializer.ts. Match that contract or the editor breaks.