Skip to content

Configuration

A Workbus deployment is one Worker: defineWorkbus(configure) returns the classes it exports and its Gateway, wrangler.jsonc binds them, and a few variables set its issuer, origin, and archival. This Worker watches production deploys and replies to each one:

worker.js
import { WorkerEntrypoint } from 'cloudflare:workers'
import { defineWorkbus } from 'workbus'
// The classes a Workbus Worker exports, and a watcher that hands every production deploy to Ops.
export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus(() => ({
watch: {
deploys: {
tail: 'deploys/ --label env=production',
sink: { kind: 'service', binding: 'SELF', method: 'onEvent' },
},
},
}))
// Each match, in order per thread; a throw is retried with backoff, up to 5 tries.
export class Ops extends WorkerEntrypoint {
async onEvent(event, context) {
if (event.type !== 'message.posted' || event.message.re !== null) return
await context.board.reply(event.message.id, 'seen by ops (match ' + context.match + ', try ' + context.attempt + ')')
}
}
export default { fetch: (request, env) => gateway(request, env) }
wrangler.jsonc
{
"name": "workbus-ops",
"main": "worker.js",
"compatibility_date": "2026-11-17",
"compatibility_flags": ["nodejs_compat"],
"durable_objects": {
"bindings": [
{ "name": "LEDGER", "class_name": "Ledger" },
{ "name": "RELAY", "class_name": "Relay" },
{ "name": "MAILBOX", "class_name": "Mailbox" },
{ "name": "INBOX", "class_name": "Inbox" }
]
},
"migrations": [
{ "tag": "v1", "new_sqlite_classes": ["Ledger", "Relay", "Mailbox"] },
{ "tag": "v2", "new_sqlite_classes": ["Inbox"] }
],
"services": [{ "binding": "SELF", "service": "workbus-ops", "entrypoint": "Ops" }],
"r2_buckets": [{ "binding": "FILES", "bucket_name": "workbus-files" }],
"worker_loaders": [{ "binding": "LOADER" }]
}

Run under wrangler dev with BOARD_ISSUER_KEY in .dev.vars:

$ wb post deploys/web 'v42 is on staging' --label env=staging
posted #3 in deploys/web
$ wb post deploys/web 'v43 is live' --label env=production
posted #4 in deploys/web
$ wb read 4
#4 jared 2026-11-20 15:31
v43 is live
labels env=production
#6 deploys 2026-11-20 15:31
seen by ops (match deploys:4, try 1)

The plain deployment, a board and nothing else, is src/worker.ts with wrangler.jsonc. Deploy and operate walks through a deploy.

function defineWorkbus<E>(configure?: (env: E) => WorkbusConfig): {
Ledger: typeof DurableObject // one per board: its log, its tables, its alarm
Relay: typeof DurableObject // live tails and held waits
Mailbox: typeof DurableObject // ordered delivery to watchers, and each sync's courier
Inbox: typeof DurableObject // each sync's webhooks, durable before the 200
Workbus: typeof WorkerEntrypoint // the service binding other Workers hold
BoardSession: typeof WorkerEntrypoint // Code Mode's sealed Board
gateway: (request: Request, env: E) => Promise<Response>
}

Export every class your wrangler.jsonc names, and BoardSession for run_code. configure runs with the Worker’s env in each Durable Object and in the Gateway, so read secrets from env inside it. With no configure, a deployment has no watchers and no syncs of its own; import { gateway } from 'workbus' is that Gateway.

type WorkbusConfig = {
watch?: Record<string, WatchConfig> // config watchers, by ID
sync?: Record<string, SyncProvider> // the board's own syncs, by key
}
type WatchConfig = { tail: string; sink: Sink }
type Sink =
| { kind: 'service'; binding: string; method?: string } // env[binding][method ?? 'onEvent'](event, context)
| { kind: 'url'; url: string; secret?: string } // POST { event, board, watcher, match, attempt }
| { kind: 'sync'; key: string } // a sync's courier; the board sets this up itself

Each watcher sees every event whose tail matches, on every board of the deployment, from when it is first deployed. A Mailbox per board and watcher delivers matches one at a time per thread, threads in parallel, each under a 5 minute lease; an error waits 1 second, doubling to 30, and after 5 tries the match is recorded failed and the thread goes on. Watchers covers both kinds of watcher.

A tail is what you’d type after wb tail: a channel (deploys), a subtree (deploys/), or nothing for every channel, then filters: --label k=v (repeatable), --by <who>, --mentions <who>, --source <key>, --text <words>, --re <id>, and --all for bookkeeping events too.

A service sink calls a method on a binding in env with (event, context). event is the feed event (cursor, type, payload, message, actor). context is { board, name, watcher, match, attempt }: name is the board’s name, and board is the board acting as the watcher, with me(), message(id), threads(query), post(channel, input), reply(id, input), react(id, emoji), label(id, change), and typing(id, status?). Its writes are the watcher’s (workbus:watch:<id>, outside the grants), and a retried match writes each one once.

A url sink POSTs the match as JSON. With a secret, x-board-signature is sha256= and the hex HMAC-SHA256 of the body; x-board-match is the match ID. Any answer but 2xx is a failed try.

Each key is one of the board’s own syncs: its webhooks arrive at /b/<board>/webhooks/<key>, an Inbox keeps them, and a courier copies what’s written in synced threads back. The providers:

import { defineWorkbus, githubProvider, linearProvider, notionProvider, slackProvider } from 'workbus'
export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus((env) => ({
sync: {
github: githubProvider({ webhookSecret: env.GITHUB_WEBHOOK_SECRET, repos: { 'acme/web': 'eng/web' }, token: env.GITHUB_TOKEN, docs: { 'acme/web': { dir: 'docs', channel: 'docs/web' } } }),
slack: slackProvider({ signingSecret: env.SLACK_SIGNING_SECRET, botToken: env.SLACK_BOT_TOKEN, channels: { C0123456789: 'support' } }),
linear: linearProvider({ webhookSecret: env.LINEAR_WEBHOOK_SECRET, apiKey: env.LINEAR_API_KEY, teams: { ENG: 'eng/issues' } }),
notion: notionProvider({ token: env.NOTION_TOKEN, webhookSecret: env.NOTION_WEBHOOK_SECRET, pages: { bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb: { channel: 'docs/handbook', slug: 'deploy', twoWay: true } } }),
},
}))
Provider Option What it is
githubProvider webhookSecret The secret GitHub signs deliveries with. Required.
repos Each owner/name and the channel its issues and pull requests come into. Required.
token What comments go back with: one secret for all, or (repo) => Promise<string> (an app’s installation token).
botUserId The app’s bot user ID, so its own comments aren’t imported again.
starts (event) => boolean: whether an event may start a thread.
docs Markdown docs per repo: { 'acme/web': { dir, channel, branch? } }. The files under dir are the docs under channel, both ways, on the repo’s default branch (asked of GitHub once); branch is for docs on another branch.
projects GitHub Projects by a name of your choosing: { roadmap: { project: 'acme/7', channel, status? } }. project is the organization and the Project’s number; channel takes its drafts; status maps Status options (field, ready, claimed, blocked, completed, canceled) to task states. Organization Projects only.
orgToken (org) => Promise<string>: an installation token for an organization, for its Projects. Required with projects.
apiBase GitHub’s REST API, https://api.github.com by default.
slackProvider signingSecret The app’s signing secret. Required.
channels Each Slack channel ID and the board channel its threads come into. Required.
botToken The xoxb- token replies go back with.
botUserId, botId The bot’s own IDs, so its echoes aren’t imported again.
apiBase Slack’s Web API, https://slack.com/api by default.
linearProvider webhookSecret The webhook’s signing secret. Required.
teams Each team key (ENG) or ID and the channel its issues come into. Required.
apiKey The lin_api_ key or OAuth token replies go back with.
botUserId The user the key acts as, so its echoes aren’t imported again.
apiUrl Linear’s GraphQL API, https://api.linear.app/graphql by default.
notionProvider token The internal integration’s secret. Required.
pages Each page ID (with or without dashes) and the doc it is: { channel, slug, twoWay? }. Without twoWay, the doc mirrors the page. Required.
webhookSecret The subscription’s verification token. Until it’s set, only Notion’s verification request is answered.
apiBase Notion’s API, https://api.notion.com by default.

Every credential is a Secret: a Worker secret’s string, or a Secrets Store binding, read when it’s first needed. The names in env are yours. A sync’s satellites write as workbus:sync:<key>. Webhooks says what each provider verifies; the sync guides set each one up.

wrangler.jsonc
{
"secrets_store_secrets": [
{ "binding": "SLACK_SIGNING_SECRET", "store_id": "<your store id>", "secret_name": "slack-signing-secret" }
]
}
Binding Kind Needed for
LEDGER Durable Object, class Ledger (SQLite) Every board. Required.
RELAY Durable Object, class Relay (SQLite) Live tails and held waits. Required.
MAILBOX Durable Object, class Mailbox (SQLite) Config watchers and each sync’s courier.
INBOX Durable Object, class Inbox (SQLite) Webhooks for the board’s own syncs. Without it, POST /webhooks/<key> answers 501 no_inbox.
FILES R2 bucket Attachments and archived history (keys under boards/<board>/). Without it, files answer 501 no_files.
LOADER Worker Loader (worker_loaders) MCP’s run_code.

Each Durable Object class is a SQLite class: declare it in new_sqlite_classes. The repo’s wrangler.jsonc adds Ledger, Relay, and Mailbox in migration v1 and Inbox in v2; keep those tags when you deploy over it, and add a new tag for a class you add later. Service bindings you add for watcher sinks are your own.

Variable Default What it sets
BOARD_ISSUER_KEY required The board’s issuer: a private ES256 JWK with a kid, as JSON. It signs people’s tokens, publishes its public half at /issuer/.well-known/jwks.json, and seals Code Mode sessions. Keep it a secret. node scripts/issuer.mjs key in packages/workbus makes one.
BOARD_ORIGIN the request’s origin The public origin: the issuer is <origin>/issuer, and a board’s URL and token audience are <origin>/b/<name>. Set it when the Worker sits behind another host, and so service bindings know a board’s URL before its first HTTP request.
ACCESS_TEAM none Your Cloudflare Access team name: with ACCESS_AUD, a request with cf-access-jwt-assertion and no bearer token is the Access user.
ACCESS_AUD none The Access application’s audience tag.
ARCHIVE on off turns archival off for every board.
ARCHIVE_SEAL_AFTER_MS 30 days Events older than this are sealed into segments on R2. 0 to 100 years.
ARCHIVE_COLD_AFTER_MS 90 days Threads with no activity this long go cold, to R2. 0 to 100 years.
ARCHIVE_FREEZE_AFTER_MS 30 days Threads cold this long have their summaries frozen into pages on R2. 0 to 100 years.
ARCHIVE_SEGMENT 1000 Events in a sealed segment. 16 to 100,000.
ARCHIVE_KEEP 1000 Events at the head that are never sealed. 1 to 10,000,000.
ARCHIVE_EVERY_MS 6 hours How often a pass runs when the last one found nothing. 50 ms to 30 days.
ARCHIVE_STEP_THREADS 50 Threads one step moves at most. 1 to 1,000.
ARCHIVE_PAUSE_MS 0 The pause between steps while there’s work. 0 to 1 hour.
ARCHIVE_PAGE_THREADS 256 Threads in a frozen page. 1 to 4,096.
ARCHIVE_BENCH unset 1 enables POST /archive/fill, which writes a bench history fast. Never on a real deployment.

A value outside its range is clamped to it. Each board can override the archive settings for itself with POST /archive (manage everywhere), and { "reset": true } goes back to the deployment’s. Archival explains the tiers.