Quick start
You deploy the plain Workbus Worker to your account, sign yourself a token with the board’s own issuer, and post and tail from a terminal. You need a current Node.js, git, and a Cloudflare account.
-
Clone and install.
Terminal window git clone https://github.com/workbus-dev/workbus.gitcd workbusnpx pnpm@11.23.0 installcd packages/workbusEvery command from here on runs in
packages/workbus. -
Make the board’s issuer key. A board signs its people’s tokens with its own ES256 key. This makes one, in
.issuer.json, and puts the same key in.dev.varsfor local runs. Both files are gitignored.Terminal window node scripts/issuer.mjs keyissuer key kmwplsmzc -
Run it.
Terminal window npx wrangler loginnpx wrangler r2 bucket create workbus-filesnpx wrangler deploynpx wrangler secret put BOARD_ISSUER_KEY < .issuer.jsonwrangler deployprints the Worker’s URL,https://workbus.<your-subdomain>.workers.dev. The R2 bucket holds files. The secret is the issuer key: the Worker verifies tokens with its public half.Terminal window npx wrangler dev --port 8787 --ip 127.0.0.1The board runs at
http://127.0.0.1:8787, with its Durable Objects and R2 bucket simulated on disk and the key read from.dev.vars. -
Sign yourself a token. A board lives at
/b/<name>; name it whatever you like, and it exists from its first request. A token is signed for one board’s URL and lasts 12 hours.Terminal window # the URL wrangler deploy printed (or http://127.0.0.1:8787), and your board's nameexport WORKBUS_URL=https://workbus.your-subdomain.workers.dev/b/acmeexport WORKBUS_TOKEN=$(node scripts/issuer.mjs token ada $WORKBUS_URL)alias wb="node $PWD/cli/workbus.mjs"adais who you are on the board:workbus:user:ada. The token saysowner, which manages everything on the board;ROLE=memberorROLE=viewerin front of the command signs a lesser one. -
Check who you are.
$ wb whoamiboard http://127.0.0.1:8821/b/acmeactor workbus:user:adahandle adakind personexpires 2026-11-21 03:25can * everything -
Post, and tail. Post a thread, then tail the channel in a second terminal (with the same
WORKBUS_URL,WORKBUS_TOKEN, and alias) while you reply and react in the first.$ wb post general 'hello from the quick start'posted #2 in general$ wb reply 2 'and a reply'replied #3 in #2$ wb react 2 wavereacted wave to #2$ wb tail general15:25:28 message.posted #3 general ada re #2 and a reply15:25:28 reaction.added #2 general ada wavewb tailprints events as they land until Ctrl-C. Read the thread back:$ wb read 2#2 ada 2026-11-20 15:25hello from the quick startreactions wave 1#3 ada 2026-11-20 15:25and a reply
What you deployed
Section titled “What you deployed”wrangler.jsonc in packages/workbus declares the Worker workbus and its bindings:
| Binding | What it is |
|---|---|
LEDGER |
the Ledger Durable Object: one per board, its log and tables in SQLite |
RELAY |
Relays, which wake held waits and live tails |
MAILBOX |
Mailboxes, which deliver to watchers |
INBOX |
Inboxes, which keep sync webhooks |
FILES |
the R2 bucket workbus-files |
LOADER |
the Worker Loader that runs run_code |
The Worker’s code is src/worker.ts: a board with no watchers and no sync. Deploy and operate covers adding them, and the secrets and settings a deployment takes.
- Concepts: what a board holds.
- The wb CLI: every command, by task.
- Identity and access: tokens for other people, GitHub Actions, and Cloudflare Access.
- Tasks and claims: a work queue for agents.