Server & Gateway API

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

startServer: self-contained HTTP server with REST routes for run lifecycle, SSE event streams, and approvals; one server, many workflows by path. Use it for a plain HTTP API with no client SDK.
createServeApp: Hono app bound to one already-loaded workflow and run; what bunx smthrs up --serve mounts. Compose it into a larger Hono app or call app.fetch in tests.
Gateway: 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: the surface the Gateway client and custom UIs talk to.

import { startServer, createServeApp, Gateway } from "smthrs";

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

startServer

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

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

ServerOptions

Show ServerOptions

number

default:"7331"

Port to bind.

unknown

Database handle. Enables GET /v1/runs and approvals listing when set.

string

Bearer token for every route but /health; falls back to process.env.SMITHERS_API_KEY, disabled when neither is set.

number

default:"1048576"

Maximum accepted request body size; larger bodies get PAYLOAD_TOO_LARGE.

string

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

boolean

default:"false"

Allow network access from the built-in bash tool.

number

default:"30000"

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

number

default:"60000"

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

object

A listening Node http.Server, with headersTimeout/requestTimeout applied to bound slow header/body uploads. 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

Builds a Hono app for a single, already-loaded workflow and run: mount it with Bun.serve, route it into another Hono app, or drive app.fetch directly in tests. Backs bunx smthrs up --serve.

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

ServeOptions

required

Show ServeOptions

SmithersWorkflow<unknown>

required

Loaded workflow instance.

SmithersDb

required

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

string

required

Active run id this app serves.

AbortController

required

Shared cancellation controller. Aborting it cancels the served run.

string

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

boolean

default:"true"

Expose /metrics (Prometheus exposition).

object

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

import { SmithersDb, createServeApp } from "smthrs";

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(). Serves RPC over POST /v1/rpc/<method> (and POST /rpc) and over WebSocket on the same origin, plus /health, /metrics, /workflows, and per-workflow webhook endpoints. 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 "smthrs";

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

Show GatewayOptions

number

default:"1"

Wire protocol version advertised to clients.

string[]

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

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

number

default:"15000"

WebSocket heartbeat interval; also clamps the cron poll interval (1-15s).

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.

string

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

GatewayOperatorUiConfig | false

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

Built-in operator browser console; set false to disable.

GatewayDefaults

Per-gateway defaults. See defaults below.

number

default:"1048576"

Maximum accepted body for POST /rpc.

number

default:"1048576"

Maximum size of a single WebSocket frame.

number

default:"1000"

Maximum concurrent connections. Over-limit upgrades get 503.

number

default:"10000"

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

boolean

default:"true"

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

number

default:"1000"

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

number

default:"30000"

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

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"

Record<string, GatewayTokenGrant>

required

Map of bearer token to its grant.

Show GatewayTokenGrant

string

required

Role assigned to requests bearing it.

string[]

required

Granted scopes; ["*"] grants all.

string

Stable user id recorded as actor.

string

Token identifier, for revocation and audit.

number

Issue time (epoch ms).

number

Expiry time (epoch ms); past tokens rejected.

number

Revocation time (epoch ms); revoked tokens rejected.

string[]

default:"[]"

Origin allowlist (defense-in-depth). [] disables the check; when non-empty, a request or WebSocket upgrade whose browser Origin header isn’t listed is rejected. Requests with no Origin (server-to-server / CLI) are always allowed.

Show mode: "jwt"

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

string

required

Expected iss claim.

string | string[]

required

Accepted aud claim(s).

string

required

HS256 shared secret.

string

default:"\"scope\""

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

string

default:"\"role\""

Claim holding role.

string

default:"\"sub\""

Claim holding user id.

string

default:"\"operator\""

Role used when role claim absent.

string[]

default:"[]"

Scopes used when scope claim absent.

number

default:"60"

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

string[]

default:"[]"

Origin allowlist (defense-in-depth); same behavior as token mode above.

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 them.

string[]

Headers read as [user, scopes, role].

string[]

default:"[]"

Origin allowlist (defense-in-depth); same behavior as token/jwt modes above, enforced identically across all auth modes.

string

default:"\"operator\""

Role used when role header absent.

string[]

default:"[\"*\"]"

Scopes used when scopes header absent.

UI config

Show GatewayUiConfig

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

string

required

Browser entry module for the React app, bundled by Smithers with Bun and served from the gateway origin.

string

Mount path: gateway-level UI defaults to /, workflow-level (via register) to /workflows/<workflowKey>.

string

Document title for the generated HTML shell.

Record<string, unknown>

JSON-serializable boot data exposed to the browser.

Show GatewayOperatorUiConfig

string

default:"\"/console\""

URL path for the built-in operator console.

string

Document title for the generated HTML shell.

Record<string, unknown>

JSON-serializable boot data exposed to the browser.

defaults

Show GatewayDefaults

"all" | "explicit-only"

Default tool exposure for CLI-launched agents.

boolean

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

number

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

register

Registers 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 = ["*"].

string

required

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

SmithersWorkflow

required

Loaded workflow instance.

GatewayRegisterOptions

Show GatewayRegisterOptions

string

Cron expression that fires the workflow on schedule.

GatewayWebhookConfig

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

GatewayUiConfig

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

Show GatewayWebhookConfig

string

required

Shared secret for HMAC signature verification.

string

Header carrying the request signature.

string

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

GatewayWebhookSignalConfig

Map a verified webhook into a run signal.

Show GatewayWebhookSignalConfig

string

required

Signal name delivered to the run.

string

JSON path to a correlation id matching the target run.

string

JSON path to an explicit run id in the payload.

string

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

GatewayWebhookRunConfig

Start a new run from a verified webhook.

Show GatewayWebhookRunConfig

boolean

Whether a webhook may launch a run.

string

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

listen / close

object

Show listen options

number

default:"7331"

TCP port to bind.

string

Host/interface to bind.

string

Unix socket path; when set, port/host are ignored.

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; exact type definitions are mirrored in Types reference.

Overview

Core API

Runtime

Types & errors

Gateway RPC

Server & Gateway API

startServer

createServeApp

Gateway

GatewayOptions

GatewayAuthConfig

UI config

defaults

register

listen / close

​startServer

​createServeApp

​Gateway

​GatewayOptions

​GatewayAuthConfig

​UI config

​defaults

​register

​listen / close

startServer

createServeApp

Gateway

GatewayOptions

GatewayAuthConfig

UI config

defaults

register

listen / close