Skip to content

Workbus from a Worker

A Worker in your account binds the board’s Workbus entrypoint and calls it over RPC. There’s no token to mint or rotate: the binding’s props say which Worker it is, and only someone who can deploy to the account can set them.

wrangler.jsonc
{
"name": "deployer",
"main": "src/index.ts",
"compatibility_date": "2026-11-17",
"services": [
{
"binding": "WORKBUS",
"service": "workbus",
"entrypoint": "Workbus",
"props": { "board": "acme", "principal": "deployer", "can": "deploys=read,post", "profile": "deployer" }
}
]
}
src/index.ts
import type { Workbus } from 'workbus'
type Env = { WORKBUS: Service<Workbus> }
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const sha = new URL(request.url).searchParams.get('sha') ?? 'unknown'
const board = env.WORKBUS.board('acme')
// The same id writes once, so a retried deploy hook doesn't post twice.
const { message } = await board.post('deploys', { text: sha + ' is live', id: 'deploy-' + sha })
await board.reply(message.id, { text: 'smoke tests pass', id: 'smoke-' + sha })
const thread = await board.read(message.id)
return Response.json({ id: message.id, by: message.by.actor, replies: thread.replies.map((reply) => reply.text) })
},
}
$ curl -s 'http://127.0.0.1:8832/?sha=f00d42'
{"id":"25","by":"worker:deployer+deployer","replies":["smoke tests pass","seen by the ops watcher (try 1)"]}
$ curl -s 'http://127.0.0.1:8832/?sha=f00d42'
{"id":"25","by":"worker:deployer+deployer","replies":["smoke tests pass","seen by the ops watcher (try 1)"]}

The second call is the same post and the same reply: each write’s id makes it land once. (The second reply in the thread is a watcher’s.) Service<Workbus> types the binding; import type from workbus brings no code into your Worker.

Prop Means
principal the Worker’s script name: it acts as worker:<principal>. Required; without it every call is refused.
board the one board it reaches. Without it, board(name) reaches any board on the deployment.
can a narrowing, as x-board-can writes it (deploys=read,post;work/=all) or as an object ({ "work/": ["read", "post"] }).
profile the profile it writes as: worker:<principal>+<profile>.

What the Worker may do is what the board’s grants give worker:<principal>, held to can. A new board’s starting grant g2 gives every Worker in the account read, post, react, label, and sync everywhere; grant one by name with wb grants create --principal '{"kind":"worker","script":"deployer"}' --can ….

env.WORKBUS.board(name) answers a Board: the board as that one caller. Every method takes what the HTTP route takes and is checked by the same schema, so a refusal is the same refusal.

Method Does
me() who this is and what it may do where
post(channel, text or { text, labels, attachments, id, noSync }) starts a thread
reply(id, text or { … }) replies in the thread of any message
read(id, { after, limit }) a thread: { message, replies, cursor }
threads({ channel, by, mentions, label, text, from, limit, before }) threads by filters
messages(channel, { after, limit }) one channel’s messages, oldest first
channels({ prefix }) the channels it can read
posted(clientId) a post by the client ID it was written with
edit(id, text), delete(id), react(id, emoji), label(id, { set, unset, if }) change a message
events({ after, last, wait, …filters }) a page of the feed; wait (up to 300 s) holds the call until something comes
schedule({ channel or re, text, in, at, every, … }), schedules(), cancelSchedule(id) scheduled messages
tasks list, create, createMany, claim, block, unblock, reopen, cancel, assign, needs
as(profile) the same caller, writing as a profile
narrow(can), channel(pattern) the same caller, held to less

A refusal is thrown as an Error whose message leads with the board’s code: forbidden: this token can't post in jobs.

narrow() and channel() answer a new Board that can do no more than this one and the narrowing both allow. Hand a piece of your Worker only the channel it needs; it can’t widen it back:

// board is env.WORKBUS.board('acme'), as above
const deploys = board.channel('deploys')
await deploys.post('deploys', 'inside') // lands
await deploys.post('jobs', 'outside') // forbidden: this token can't post in jobs
await deploys.narrow('*=all').post('jobs', 'still outside') // forbidden: it never widens

board.tasks.claim() answers a Claim, or null when nothing was ready. The claim’s token stays on the server; every call on it is fenced by it.

// board is env.WORKBUS.board('acme'), as above.
// The oldest ready task in jobs that ada made, held up to 60 s until there is one.
const claim = await board.tasks.claim({ channel: 'jobs', from: ['workbus:user:ada'] }, { wait: 60, lease: 300 })
if (claim) {
await claim.renew(600) // seconds; answers the new until
await claim.complete('done') // or fail(reason), release(), block(reason)
}

Dropping a Claim doesn’t release the task; the claim lasts until its lease ends. claim.sturdy() hands out { id, epoch, token } for a process that outlives this one, and a claim made with a token you chose ({ token }, 32 bytes base64url) can be taken up again with the same token. Tasks and claims has the rest.

A board learns its URL from the first request it serves with a caller. A Worker that calls a board through the binding before anyone has used it over HTTP gets:

WorkbusError: no_mount: this board hasn't been served at its URL yet, so it doesn't know its own address: set BOARD_ORIGIN, or make one request to it first

Set BOARD_ORIGIN on the board’s Worker to the origin people reach it at (https://workbus.example.com), and bindings work from the first call. See Deploy and operate.