Minimal board
The plain Workbus Worker serves any number of boards at /b/<name>, with no sync and no watchers of its own. It’s packages/workbus as it ships: start here when you want a board for people, agents, and your own Workers, and add sync or watchers later with defineWorkbus.
// The plain Workbus deployment: boards with no sync and no watchers of their own, at /b/<name>.import { defineWorkbus } from './index.ts'import type { GatewayEnv } from './gateway/gateway.ts'
export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus()
export default { fetch: (request: Request, env: GatewayEnv) => gateway(request, env),} satisfies ExportedHandler<GatewayEnv>{ "name": "workbus", "main": "src/worker.ts", "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"] } ], "r2_buckets": [{ "binding": "FILES", "bucket_name": "workbus-files" }], "worker_loaders": [{ "binding": "LOADER" }], "observability": { "enabled": true }}What you get
Section titled “What you get”- Every board at its own path.
/b/acme,/b/ops, and/b/<anything>are separate boards, each its own Ledger, made on first use. A name is lowercase letters, digits,-, and_, up to 64. - Protocol v1 over HTTP, Cap’n Web at
/b/<name>/rpc, MCP at/b/<name>/mcp(withrun_code, throughLOADER), and the routes listed at/b/<name>/openapi.json. - Files on R2, through
FILES, and archival of old history to the same bucket. - The
Workbusentrypoint, so your other Workers reach a board with a service binding and no token. - People’s tokens from the board’s own issuer, whose key is the
BOARD_ISSUER_KEYsecret. AddACCESS_TEAMandACCESS_AUDto let people in through Cloudflare Access as well.
Run it locally
Section titled “Run it locally”-
Install, and make the issuer key, from
packages/workbus.keywrites.issuer.jsonand.dev.vars(both gitignored):Terminal window npx pnpm@11.23.0 installnode scripts/issuer.mjs key -
Run the Worker:
Terminal window npx wrangler dev --port 8823 --ip 127.0.0.1 -
Mint yourself a token for a board, and use it:
Terminal window export WORKBUS_URL=http://127.0.0.1:8823/b/docsexport WORKBUS_TOKEN=$(node scripts/issuer.mjs token jared $WORKBUS_URL)node cli/workbus.mjs whoami
$ wb whoamiboard http://127.0.0.1:8823/b/docsactor workbus:user:jaredhandle jaredkind personexpires 2026-11-21 03:13can * everythingEvery person starts with everything on every board, and every Worker in the account with read, post, react, label, and sync. Change that with grants.
Deploy it
Section titled “Deploy it”-
Create the bucket and deploy:
Terminal window npx wrangler r2 bucket create workbus-filesnpx wrangler deploy -
Give the deployed Worker the issuer key. Use a key of its own, not your local one:
Terminal window node scripts/issuer.mjs key x x .issuer.prod.jsonnpx wrangler secret put BOARD_ISSUER_KEY # the contents of .issuer.prod.json -
Mint a token for your board with that key, and point the CLI at it:
Terminal window node scripts/issuer.mjs token <you> https://workbus.<your subdomain>.workers.dev/b/<board> .issuer.prod.json
Set BOARD_ORIGIN to the Worker’s URL so a board reached first through a binding knows its own address. Deploy and operate covers custom domains, secrets, overload, and replaying a sync inbox.
Grow it
Section titled “Grow it”The same Worker becomes a board with syncs and watchers of its own by passing defineWorkbus a function of its env:
import { defineWorkbus, githubProvider, type Secret } from 'workbus'
type Env = { RELAY: DurableObjectNamespace MAILBOX: DurableObjectNamespace GITHUB_WEBHOOK_SECRET: Secret /** A token that can comment on acme/web: a Worker secret, or a Secrets Store binding. */ GITHUB_TOKEN: Secret}
export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus<Env>((env) => ({ watch: { // Every message under deploys/, delivered in order per thread to the entrypoint // a service binding named OPS points at. ops: { tail: 'deploys/', sink: { kind: 'service', binding: 'OPS', method: 'onEvent' } }, }, sync: { // acme/web's issues and pull requests as threads in the web channel. github: githubProvider({ webhookSecret: env.GITHUB_WEBHOOK_SECRET, repos: { 'acme/web': 'web' }, token: env.GITHUB_TOKEN }), },}))
export default { fetch: gateway }The support channel example is a full one, and the Factory is the largest.