A workbook is a single .org file that runs — prose, code, and data in one artifact that publishes as a live page. You don't have to write it yourself. In this tutorial you'll stand up a local runtime, tell an agent what you want in plain English, watch it author the workbook for you, and deploy it to a URL.

One happy path, start to finish, about ten minutes. You need a terminal and the wbx CLI — nothing else on your machine. The compilers, the model, and the sandbox all live inside the runtime.

The CLI is wbx. Every command below is real and pinned to where it lives in the code. Engine-backed commands (build, agent, deploy) talk to a runtime you start in step 2 — they don't need anything else installed. :SRC: cli/src/main.rs:24

One line installs the wbx binary. The toolchains it needs are not installed here — they live in the runtime as WASM and provision on first use.

curl -fsSL https://workbooks.sh/install.sh | sh
wbx --help

If wbx --help prints the verb list, you're ready.

The agent thinks, compiles, and runs inside a runtime engine. wbx deploy local scaffolds a local config if there isn't one, then converges to a running container on your machine — one command.

wbx deploy local
wbx deploy status     # confirm it's up

wbx deploy local is the shorthand: it writes a deployment.org if absent, then applies it (a docker / podman container, or a krunvm microVM on macOS). :SRC: cli/src/deploy/mod.rs:48

For the agent to think, the runtime needs one secret: an OpenRouter API key. You set it as a deployment secret — it lives host-side and the agent never sees it.

wbx deploy secrets set OPENROUTER_API_KEY=sk-or-...
wbx deploy apply        # re-converge so the runtime picks it up

The key is stored under the name OPENROUTER_API_KEY; wbx deploy secrets list shows the names (never the values). :SRC: cli/src/deploy/mod.rs:60

Describe the workbook in plain English. wbx agent run starts a long-horizon run on the runtime and returns an id you poll — the agent works in the background.

wbx agent run "Make a workbook that shows the current weather \
for three cities I name, with a small chart."
# → returns a run id, e.g. run_a1b2c3

Under the hood that's a POST /api/run to the engine; the system prompt defaults to a careful, capable agent, and you can pass --model to choose one. :SRC: cli/src/commands.rs:103

Poll the run with its id. Repeat until the status shows it's done; the result includes the workbook the agent authored.

wbx agent status run_a1b2c3

If the draft isn't quite right, tell the agent again in the same plain-English way with another wbx agent run — directing it is the loop. When you're happy, save the workbook the agent produced as a file, e.g. weather.org.

Give the workbook an id and deploy its source to the runtime. It's now live and listed.

wbx workbook deploy weather weather.org
# → deployed weather.org → /w/weather
wbx workbook list                         # see it among your deployed workbooks

wbx workbook deploy <id> <file> reads the org source and PUT=s it to =/w/<id> on the engine — that path is your live workbook. :SRC: cli/src/commands.rs:120

You installed one CLI, stood up a runtime, directed an agent in plain English to author a workbook, watched it work, and deployed the result to a URL — without writing the workbook by hand and without a compiler on your machine.

From here:

• Author one yourself — scaffold a blank workbook with wbx init and edit the .org directly. See Your first toolkit for the build-and-run loop.

• Understand what a workbook is → Workbooks & toolkits.

• Ship it further → Publish to the open web.

North-star: a fully no-terminal version of this — say what you want, get a deployed workbook, all inside the desktop app — is where this is heading. Today the path above is the real, working one and it runs from a single CLI. :SRC: cli/src/main.rs:188