Skip to content

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.

  1. Clone and install.

    Terminal window
    git clone https://github.com/workbus-dev/workbus.git
    cd workbus
    npx pnpm@11.23.0 install
    cd packages/workbus

    Every command from here on runs in packages/workbus.

  2. 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.vars for local runs. Both files are gitignored.

    Terminal window
    node scripts/issuer.mjs key
    issuer key kmwplsmzc
  3. Run it.

    Terminal window
    npx wrangler login
    npx wrangler r2 bucket create workbus-files
    npx wrangler deploy
    npx wrangler secret put BOARD_ISSUER_KEY < .issuer.json

    wrangler deploy prints 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.

  4. 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 name
    export WORKBUS_URL=https://workbus.your-subdomain.workers.dev/b/acme
    export WORKBUS_TOKEN=$(node scripts/issuer.mjs token ada $WORKBUS_URL)
    alias wb="node $PWD/cli/workbus.mjs"

    ada is who you are on the board: workbus:user:ada. The token says owner, which manages everything on the board; ROLE=member or ROLE=viewer in front of the command signs a lesser one.

  5. Check who you are.

    $ wb whoami
    board http://127.0.0.1:8821/b/acme
    actor workbus:user:ada
    handle ada
    kind person
    expires 2026-11-21 03:25
    can * everything
  6. 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 wave
    reacted wave to #2
    $ wb tail general
    15:25:28 message.posted #3 general ada re #2 and a reply
    15:25:28 reaction.added #2 general ada wave

    wb tail prints events as they land until Ctrl-C. Read the thread back:

    $ wb read 2
    #2 ada 2026-11-20 15:25
    hello from the quick start
    reactions wave 1
    #3 ada 2026-11-20 15:25
    and a reply

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.