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 24 LTS (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:9970


# Clerk is required in local and deployed environments.
CLERK_SECRET_KEY=...
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 and sign in with Clerk.
  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, retired (removed). 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 wiring has been deleted along with flank’s server-side engine; brain owns all workflow data.

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.
  • Clerk is required — Flank validates the Clerk session and forwards a bearer token to Brain. There is no current environment-driven authentication bypass.
  • 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.