Serve Mode

Serve mode starts a Hono-based HTTP server alongside a running workflow. Every route operates on the single active run: no workflow path or run ID in requests.

API reference: Server & Gateway lists every server and gateway export, its options, and links to source and tests.

CLI

bunx smthrs up workflow.tsx --serve --port 3000 --host 0.0.0.0 --auth-token "$SMITHERS_API_KEY"

A non-loopback --host (like 0.0.0.0) requires --auth-token (or --insecure, dangerous). The default 127.0.0.1 needs neither.

Flag	Default	Description
`--serve`	`false`	Enable HTTP server mode
`--port`	`7331`	TCP port
`--host`	`127.0.0.1`	Bind address
`--auth-token`	`SMITHERS_API_KEY` env	Bearer token for auth; required for a non-loopback `--host`
`--insecure`	`false`	Allow a non-loopback `--host` with no auth (exposes unauthenticated approve/deny/cancel; dangerous)
`--metrics`	`true`	Expose `/metrics` Prometheus endpoint
`--supervise`	`false`	Run the stale-run supervisor loop alongside `--serve`

The process stays alive after the workflow completes, so final state stays queryable. Ctrl+C stops both server and workflow. Detached mode:

bunx smthrs up workflow.tsx --serve --port 8080 -d

Programmatic

import { SmithersDb, createServeApp } from "smthrs";

const adapter = new SmithersDb(workflow.db);
const abort = new AbortController();

const app = createServeApp({
  workflow,
  adapter,
  runId,
  abort,
  authToken: "sk-secret",
});

Bun.serve({ port: 3000, fetch: app.fetch });

createServeApp returns a standard Hono app. Mount it with Bun.serve, pass it to another Hono app via app.route(), or use app.fetch in tests.

ServeOptions

type ServeOptions = {
  workflow: SmithersWorkflow<unknown>;   // loaded workflow instance
  adapter: SmithersDb;               // Smithers DB adapter; e.g. new SmithersDb(workflow.db)
  runId: string;                     // active run ID
  abort: AbortController;            // shared cancellation controller
  authToken?: string;                // bearer token; falls back to SMITHERS_API_KEY; disabled if unset
  metrics?: boolean;                 // expose /metrics; default true
};

Authentication

When authToken is configured, every route except /health requires:

Authorization: Bearer <token>, or
x-smithers-key: <token>

Missing or invalid tokens receive 401.

Routes

GET /health

Returns 200 regardless of auth.

{ "ok": true }

GET /

Run status and node summary.

{
  "runId": "run-1234",
  "workflowName": "bugfix",
  "status": "running",
  "startedAtMs": 1707500000000,
  "finishedAtMs": null,
  "summary": { "finished": 3, "in-progress": 1, "pending": 2 }
}

GET /events

SSE stream of lifecycle events, same format as the multi-workflow server.

Parameter	Type	Default	Description
`afterSeq`	`number`	`-1`	Only events after this sequence

event: smithers
data: {"type":"NodeStarted","runId":"run-1234","nodeId":"analyze","iteration":0,"attempt":1}
id: 1

event: smithers
data: {"type":"NodeFinished","runId":"run-1234","nodeId":"analyze","iteration":0,"attempt":1}
id: 2

Polls every 500ms.
Auto-closes when the run reaches a terminal state.
Reconnect with ?afterSeq=N to resume.

GET /frames

Rendered workflow frames.

Parameter	Type	Default	Description
`limit`	`number`	`50`	Max frames
`afterFrameNo`	`number`	-	Frames after this number

POST /approve/:nodeId

Approve a pending approval gate. All fields optional. Returns { "runId": "run-1234" }.

{
  "iteration": 0,
  "note": "Looks good",
  "decidedBy": "alice",
  "decision": { "selected": "balanced", "notes": "best fit" }
}

For select and rank approvals, decision must contain a valid selection or ranking. A stable decision envelope with value is also accepted.

POST /deny/:nodeId

Deny a pending approval gate. Same body as /approve/:nodeId.

POST /cancel

Cancel the running workflow.

Status	Code	Condition
200	-	Cancelled successfully
409	`RUN_NOT_ACTIVE`	Run is not actively running (e.g. already finished, failed, cancelled, continued, or its heartbeat has gone stale)

Note: Runs in waiting-approval or waiting-timer state are cancelled immediately and return 200.

GET /metrics

Prometheus text exposition, same metrics as the multi-workflow server.

Error Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Unknown routes return 404 with code NOT_FOUND.

Serve Mode vs Multi-Workflow Server

	Serve mode	Multi-workflow server
Scope	Single workflow, single run	Any workflow, multiple concurrent runs
Start	`bunx smthrs up --serve` or `createServeApp()`	`startServer()`
Routes	`/`, `/events`, `/approve/:nodeId`, …	`/v1/runs`, `/v1/runs/:runId`, …
Framework	Hono	Node.js `http`
Use case	Development, single-purpose services	Production API gateway

Example

# Start a workflow with serve mode
bunx smthrs up workflow.tsx --serve --port 8080 --auth-token sk-secret

# Status
curl http://localhost:8080/ -H "Authorization: Bearer sk-secret"

# Stream events
curl -N http://localhost:8080/events -H "Authorization: Bearer sk-secret"

# Approve
curl -X POST http://localhost:8080/approve/deploy \
  -H "Authorization: Bearer sk-secret" \
  -H "Content-Type: application/json" \
  -d '{"note": "Ship it", "decidedBy": "alice"}'

# Health (no auth)
curl http://localhost:8080/health

Start

Articles

Learn

Capabilities

Build Workflows

Run and Operate

Workflow Pack

Components

Integrations

Agent Support

Examples

Contributing

CLI

Programmatic

ServeOptions

Authentication

Routes

GET /health

GET /

GET /events

GET /frames

POST /approve/:nodeId

POST /deny/:nodeId

POST /cancel

GET /metrics

Error Format

Serve Mode vs Multi-Workflow Server

Example

​CLI

​Programmatic

​ServeOptions

​Authentication

​Routes

​GET /health

​GET /

​GET /events

​GET /frames

​POST /approve/:nodeId

​POST /deny/:nodeId

​POST /cancel

​GET /metrics

​Error Format

​Serve Mode vs Multi-Workflow Server

​Example

CLI

Programmatic

ServeOptions

Authentication

Routes

GET /health

GET /

GET /events

GET /frames

POST /approve/:nodeId

POST /deny/:nodeId

POST /cancel

GET /metrics

Error Format

Serve Mode vs Multi-Workflow Server

Example