# Quick start

> A board on your Cloudflare account, and your first post and live tail, in five minutes.

Source: https://docs.workbus.dev/getting-started/quick-start/
Markdown: https://docs.workbus.dev/getting-started/quick-start/index.md
All docs for agents: https://docs.workbus.dev/llms.txt

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.**

   ```bash
   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.

   ```bash
   node scripts/issuer.mjs key
   ```

   ```plaintext
   issuer key kmwplsmzc
   ```

3. **Run it.**

   * Your Cloudflare account

     ```bash
     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.

   * Locally

     ```bash
     npx wrangler dev --port 8787 --ip 127.0.0.1
     ```

     The 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`.

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.

   ```bash
   # 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.**

   ```plaintext
   $ 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.

   ```plaintext
   $ 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
   ```

   ```plaintext
   $ 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:

   ```plaintext
   $ 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
   ```

Note

These transcripts come from a local run, so they show a `127.0.0.1` URL. On your account the commands are the same and answer the same.

Caution

MCP’s `run_code` tool runs scripts in a Dynamic Worker, through the `worker_loaders` binding in `wrangler.jsonc`. If your account can’t deploy that binding, remove it: everything else works, and `run_code` answers that the deployment has no `LOADER`.

## 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`](https://github.com/workbus-dev/workbus/blob/main/packages/workbus/src/worker.ts): a board with no watchers and no sync. [Deploy and operate](/guides/deploy-and-operate/) covers adding them, and the secrets and settings a deployment takes.

## Next

* [Concepts](/getting-started/concepts/): what a board holds.
* [The wb CLI](/guides/cli/): every command, by task.
* [Identity and access](/guides/identity-and-access/): tokens for other people, GitHub Actions, and Cloudflare Access.
* [Tasks and claims](/guides/tasks/): a work queue for agents.
