fh dev

fabric-harness dev [--target node|cloudflare|temporal-worker] [options]

fh dev boots the selected target's development server and watches both .fabricharness/jobs/ and .fabricharness/agents/. The Node target uses the same v2 server as Node-derived builds. Cloudflare uses Wrangler for finite jobs and Durable Object-backed persistent agents.

Routes

GET /health
GET /ready
POST /jobs/:name — invoke a finite job with its JSON input.
POST /agents/:name/:id — durably admit a persistent message and return 202.
GET /agents/:name/:id/stream?offset=... — tail persistent conversation records.
GET /builds/:target/manifest — read a build manifest still under the workspace.

Cloudflare also exposes GET /manifest; persistent instances use Durable Objects for FIFO submissions, leases, conversation streams, abort, and deletion.

Options

Flag	Description
`--target <node\|cloudflare\|temporal-worker>`	Default `node`.
`--env <file>`	Load `.env`-style variables. Repeatable; shell env wins.
`--mock`	Use the deterministic mock model provider for every request.
`--console`	Open the Fiber terminal UI after the Node target starts; unsupported for Cloudflare and Temporal targets.
`--host <host>`	Listen address (default `127.0.0.1`).
`--port <port>`	Listen port (default `3000`; the CLI selects the next available port when it is busy).
`--auth-token-env <var>`	Require `Authorization: Bearer $$VAR` for invocations.
`--max-body-bytes <n>`	Reject request bodies larger than `n`.
`--rate-limit-window-ms <n>`	Rate-limit window in ms.
`--rate-limit-max <n>`	Rate-limit max requests per window.

Example

fh dev --mock --port 4000 --auth-token-env FABRIC_DEV_TOKEN

Or keep the server and operator view in one process:

FABRIC_DEV_TOKEN=local-token fh dev --mock --console --auth-token-env FABRIC_DEV_TOKEN

curl -X POST \
  -H "Authorization: Bearer $FABRIC_DEV_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"question":"What is Temporal?"}' \
  http://localhost:4000/jobs/ask

When to use which

fh run — one-shot invocations, scripts, CI smoke tests.
fh dev — local development with hot reload, finite job webhook testing, and durable persistent-agent streams.

See HTTP Server for the complete Node route table.

Transport-free runs

fh run loads the selected public definition directly and does not start an HTTP listener. Finite agents continue to accept JSON payloads. Persistent agents accept a message and durable instance identity controls:

fh run support --id customer-42 --new \
  --data '{"account":"acme"}' --prompt "Triage this request"

# Continue only the incarnation printed by the first command.
fh run support --id customer-42 --uid inst_... --prompt "Continue"

Initial data is schema-validated before instance identity or conversation records are committed. --new fails if the instance already exists, --uid fails if the instance is missing or has been replaced, and the command prints the resolved UID to stderr. SIGINT/SIGTERM cancels the active finite or persistent run and interaction-scoped dynamic sandboxes are reclaimed when it settles.

Projects that already use Vite 8 can instead add fabricHarness() from @fabric-harness/vite; see Vite integration. This is optional and uses the same discovery/build registry as fh dev and fh build.