Server & Gateway API

Three host surfaces ship from packages/server, each a tighter fit for a different deployment.

startServer: a self-contained HTTP server with REST routes for run lifecycle, SSE event streams, and approvals. One server, many workflows by path. Reach for it when you want a plain HTTP API and no client SDK.
createServeApp: a Hono app bound to one already-loaded workflow and run. This is what bunx smithers-orchestrator up --serve mounts. Compose it into a larger Hono app or call app.fetch in tests.
Gateway: the headless control plane. Authenticate once, stream events over WebSocket with resume-on-reconnect, decide approvals, inject signals, run cron schedules, and serve many registered workflows. This is the surface the Gateway client and custom UIs talk to.

import { startServer, createServeApp, Gateway } from "smithers-orchestrator";

createServeApp needs a SmithersDb adapter and a loaded SmithersWorkflow; both come from your workflow module (new SmithersDb(workflow.db)). The Gateway is constructed with new Gateway(opts), then you register() workflows and listen().

startServer

Boot a listening http.Server exposing REST run lifecycle, SSE streams, and approval routes. Synchronous: it returns the bound server immediately.

function startServer(opts?: ServerOptions): import("node:http").Server;

opts

ServerOptions

Show ServerOptions

port

number

default:"7331"

Port to bind.

unknown

Database handle. When set, enables GET /v1/runs and approvals listing.

authToken

string

Bearer token required on every route except /health. Falls back to process.env.SMITHERS_API_KEY; auth is disabled when neither is set.

maxBodyBytes

number

default:"1048576"

Maximum accepted request body size. Larger bodies get PAYLOAD_TOO_LARGE.

rootDir

string

Sandbox root that workflow paths and tools resolve against. Paths outside it are rejected with WORKFLOW_PATH_OUTSIDE_ROOT.

allowNetwork

boolean

default:"false"

Allow network access from the built-in bash tool.

headersTimeout

number

default:"30000"

Maximum time (ms) the HTTP parser may take to receive complete request headers. Mitigates slowloris.

requestTimeout

number

default:"60000"

Maximum time (ms) to receive and parse a single request, body included.

http.Server

object

A listening Node http.Server. headersTimeout and requestTimeout are applied to it to bound slow header/body uploads. The full route table (run start/resume/cancel, SSE events, frames, approvals, signals, /metrics) lives in Server Mode.

const server = startServer({
  port: 7331,
  authToken: process.env.SMITHERS_API_KEY,
  rootDir: process.cwd(),
});

Source index.js · ServerOptions.ts · Tests server.test.js · See also Server Mode, Control-plane deployment

createServeApp

Build a Hono app for a single, already-loaded workflow and run. Returns a standard Hono app: mount it with Bun.serve, route it into another Hono app, or drive app.fetch directly in tests. This backs bunx smithers-orchestrator up --serve.

function createServeApp(opts: ServeOptions): import("hono").Hono;

opts

ServeOptions

required

Show ServeOptions

workflow

SmithersWorkflow<unknown>

required

The loaded workflow instance.

adapter

SmithersDb

required

Smithers DB adapter, e.g. new SmithersDb(workflow.db).

runId

string

required

The active run id this app serves.

abort

AbortController

required

Shared cancellation controller. Aborting it cancels the served run.

authToken

string

Bearer token for every route except /health. Falls back to SMITHERS_API_KEY; disabled when unset. Accepts Authorization: Bearer or x-smithers-key.

metrics

boolean

default:"true"

Expose /metrics (Prometheus exposition).

Hono

object

A Hono app. Routes (/health, run status, SSE events, approvals, signals, /metrics) are documented in Serve Mode.

import { SmithersDb, createServeApp } from "smithers-orchestrator";

const abort = new AbortController();
const app = createServeApp({
  workflow,
  adapter: new SmithersDb(workflow.db),
  runId: "RUN_ID",
  abort,
  authToken: process.env.SMITHERS_API_KEY,
});
Bun.serve({ port: 7331, fetch: app.fetch });

Source serve.js · ServeOptions.ts · Tests serve.test.js · See also Serve Mode, Server Mode

Gateway

The multi-run control plane. Construct it, register() one or more workflows, then listen(). It serves RPC over POST /v1/rpc/<method> (and POST /rpc) and over WebSocket on the same origin, with a /health, /metrics, /workflows, and per-workflow webhook endpoints. The RPC methods (launchRun, getRun, listRuns, submitApproval, submitSignal, cron, time-travel, and more) are documented per method; see launchRun for the request/response and scope shape they share.

class Gateway {
  constructor(options?: GatewayOptions);
  register(key: string, workflow: SmithersWorkflow, options?: GatewayRegisterOptions): this;
  extend(namespace: string, definition: unknown): this;
  listen(options?: { port?: number; host?: string; path?: string }): Promise<import("node:http").Server>;
  close(): Promise<void>;
}

register, extend, and the constructor are chainable. listen defaults to port 7331; pass path for a Unix socket. close aborts active runs, drains inflight work, and tears down connections and the scheduler.

import { Gateway } from "smithers-orchestrator";

const gateway = new Gateway({
  heartbeatMs: 15_000,
  auth: {
    mode: "token",
    tokens: { "operator-token": { role: "operator", scopes: ["*"] } },
  },
});

gateway.register("deploy", deploy, { schedule: "0 8 * * 1-5" });
await gateway.listen({ port: 7331 });

GatewayOptions

options

GatewayOptions

Show GatewayOptions

protocol

number

default:"1"

Wire protocol version advertised to clients.

features

string[]

default:"[\"streaming\", \"runs\"]"

Feature flags advertised on /health and in the connect handshake.

heartbeatMs

number

default:"15000"

WebSocket heartbeat interval. Also clamps the cron poll interval (1 s to 15 s).

auth

GatewayAuthConfig

Authentication mode. Omit to leave the gateway unauthenticated. See auth below.

GatewayUiConfig

Custom gateway-level UI. true mounts the built-in operator console at /. See UI config below.

workspaceRoot

string

Absolute path to the workspace root that holds .smithers/ and smithers.db. Disk-backed registry reads (e.g. the listPrompts RPC) resolve against it. Defaults to process.cwd().

operatorUi

GatewayOperatorUiConfig | false

default:"{ path: \"/console\" }"

Built-in operator browser console. Set false to disable.

defaults

GatewayDefaults

Per-gateway defaults. See defaults below.

maxBodyBytes

number

default:"1048576"

Maximum accepted body for POST /rpc.

maxPayload

number

default:"1048576"

Maximum size of a single WebSocket frame.

maxConnections

number

default:"1000"

Maximum concurrent connections. Over-limit upgrades get 503.

eventWindowSize

number

default:"10000"

Per-run replay window for run event streams, in frames.

outOfProcessEventBridge

boolean

default:"true"

Bridge persisted run events from the workspace DB into live streams for runs executed by another process.

outOfProcessEventBridgePollMs

number

default:"1000"

Poll interval (ms) for the out-of-process event bridge.

headersTimeout

number

default:"30000"

Maximum time (ms) to receive complete request headers. Applied to the Node HTTP server on listen().

requestTimeout

number

default:"60000"

Maximum time (ms) to receive and parse a single request.

GatewayAuthConfig

A discriminated union on mode. Runs started through an authenticated gateway expose ctx.auth = { triggeredBy, role, scopes, createdAt }.

Show mode: "token"

tokens

Record<string, GatewayTokenGrant>

required

Map of bearer token to its grant.

Show GatewayTokenGrant

role

string

required

Role assigned to requests bearing this token.

scopes

string[]

required

Granted scopes; ["*"] grants all.

userId

string

Stable user id recorded as the actor.

tokenId

string

Identifier for the token, for revocation and audit.

issuedAtMs

number

Issue time (epoch ms).

expiresAtMs

number

Expiry time (epoch ms); past tokens are rejected.

revokedAtMs

number

Revocation time (epoch ms); revoked tokens are rejected.

Show mode: "jwt"

Validates alg=HS256, HMAC, iss, aud, exp, nbf.

issuer

string

required

Expected iss claim.

audience

string | string[]

required

Accepted aud claim(s).

secret

string

required

HS256 shared secret.

scopesClaim

string

default:"\"scope\""

Claim holding scopes (array or space/comma-separated string).

roleClaim

string

default:"\"role\""

Claim holding the role.

userClaim

string

default:"\"sub\""

Claim holding the user id.

defaultRole

string

default:"\"operator\""

Role used when the role claim is absent.

defaultScopes

string[]

default:"[]"

Scopes used when the scope claim is absent.

clockSkewSeconds

number

default:"60"

Allowed exp/nbf skew. Negative values clamp to 0.

Show mode: "trusted-proxy"

Identity is read from request headers. Only safe behind a proxy you control (Cloudflare Access, an internal API gateway) that strips and rewrites these headers.

trustedHeaders

string[]

Headers read as [user, scopes, role].

allowedOrigins

string[]

default:"[]"

Origin allowlist. [] means no Origin check is enforced.

defaultRole

string

default:"\"operator\""

Role used when the role header is absent.

defaultScopes

string[]

default:"[\"*\"]"

Scopes used when the scopes header is absent.

UI config

Show GatewayUiConfig

true mounts the built-in operator console. Otherwise an object:

entry

string

required

Browser entry module for the React app. Smithers bundles it with Bun and serves it from the gateway origin.

path

string

Mount path. Gateway-level UI defaults to /; workflow-level UI (via register) defaults to /workflows/<workflowKey>.

title

string

Document title for the generated HTML shell.

props

Record<string, unknown>

JSON-serializable boot data exposed to the browser.

Show GatewayOperatorUiConfig

path

string

default:"\"/console\""

URL path for the built-in operator console.

title

string

Document title for the generated HTML shell.

props

Record<string, unknown>

JSON-serializable boot data exposed to the browser.

defaults

Show GatewayDefaults

cliAgentTools

"all" | "explicit-only"

Default tool exposure for CLI-launched agents.

outOfProcessEventBridge

boolean

Default for the out-of-process event bridge when the top-level option is unset.

outOfProcessEventBridgePollMs

number

Default bridge poll interval (ms) when the top-level option is unset.

register

Register a workflow under key. Wires up its DB tables, optional cron schedule, webhook config, and embedded UI bundle. Returns this, so calls chain. A schedule writes a cron row keyed gateway:<key>; cron-fired runs get ctx.auth.role = "system", triggeredBy = "cron:gateway", scopes = ["*"].

key

string

required

Workflow key. Becomes the path segment for workflow-level UI and webhooks.

workflow

SmithersWorkflow

required

The loaded workflow instance.

options

GatewayRegisterOptions

Show GatewayRegisterOptions

schedule

string

Cron expression. Fires the workflow on schedule.

webhook

GatewayWebhookConfig

Inbound webhook config for POST /webhooks/<key>. See below.

GatewayUiConfig

Workflow-level UI, mounted at /workflows/<key> by default.

Show GatewayWebhookConfig

secret

string

required

Shared secret for HMAC signature verification.

signatureHeader

string

Header carrying the request signature.

signaturePrefix

string

Prefix stripped from the signature value before comparison (e.g. "sha256=").

signal

GatewayWebhookSignalConfig

Map a verified webhook into a run signal.

Show GatewayWebhookSignalConfig

name

string

required

Signal name delivered to the run.

correlationIdPath

string

JSON path to a correlation id used to match the target run.

runIdPath

string

JSON path to an explicit run id in the payload.

payloadPath

string

JSON path to the sub-payload delivered with the signal.

run

GatewayWebhookRunConfig

Start a new run from a verified webhook.

Show GatewayWebhookRunConfig

enabled

boolean

Whether a webhook may launch a run.

inputPath

string

JSON path to the sub-payload used as the run input.

listen / close

options

object

Show listen options

port

number

default:"7331"

TCP port to bind.

host

string

Host/interface to bind.

path

string

Unix socket path. When set, port/host are ignored.

listen

Promise<http.Server>

Resolves once the server is bound and the scheduler and event bridge have started.

Promise<void>

Aborts active runs, awaits inflight work, closes connections, and stops the scheduler and watchers.

Source gateway.js · GatewayOptions.ts · GatewayAuthConfig.ts · Tests gateway.test.jsx · See also Gateway, Control-plane deployment, launchRun, Gateway client

For the full route tables and wire shapes, see Server Mode, Serve Mode, and Gateway. The exact type definitions are mirrored in the Types reference.

​startServer

​createServeApp

​Gateway

​GatewayOptions

​GatewayAuthConfig

​UI config

​defaults

​register

​listen / close

startServer

createServeApp

Gateway

GatewayOptions

GatewayAuthConfig

UI config

defaults

register

listen / close