Concepts

Boardwalk has a small vocabulary. Read this page once and the rest of the docs (and the dashboard) will read naturally.

The package is the source of truth: the descriptor is read as data, and the I/O schemas are derived from run's type annotations at deploy.

Workflow

The unit you build, version, trigger, and run. A workflow has a slug (its identity) and an optional title, a version history, triggers, and a run history. Agent is not a noun Boardwalk uses for this: the thing your org owns is a workflow; agent() is a call a workflow makes when it wants a model to do some work.

Program

A workflow's source: a package directory holding a workflow.jsonc descriptor and an entry file that exports a run function the platform calls (src/index.ts in TypeScript, main.py in Python). The entry imports whatever helper modules it needs, and the package can ship bundled assets beside the code (a skills/ folder, prompt templates, a README.md). It is real code, with your packages, your editor, and your tests; the CLI builds it to a single artifact at deploy. See Writing workflows.

Descriptor & manifest

The descriptor (workflow.jsonc) is the deployment policy you write by hand: triggers, permissions, budget, concurrency, machine. It is data, so the control plane reads it without ever executing your code. The manifest is what Boardwalk stores at deploy: the descriptor plus the input and output schemas derived from your runfunction's type annotations. The manifest can't drift from the code because it is derived from the code. See The descriptor.

Run

One execution of a workflow. A run has a status (queued → running → completed / failed / cancelled), a streamed event log (phases, agent turns, output), and a permanent record in the dashboard. The run's output is the value your run function returns. Runs are real processes: locals survive a sleep, and a crash restarts the run from the top.

Trigger

What starts a run: cron (a schedule), webhook (an HTTP call), github, linear, jira or notion (an event from a provider your org has connected), manual (you, the CLI, or another workflow), or workflow_run(another workflow's run finishing). Declared in the descriptor's triggers. See Triggers.

Engine

What executes the program. The same package runs under two engines: the self-hosted single-node server (your hardware) and Boardwalk itself (hosted). Engine-dependent behavior is deliberate and small: where secrets resolve from, and what happens when agent() names no model. A shared conformance suite keeps the engines honest.