Literate Programming

Most code is written for the machine first and the human second. The machine gets a precise list of instructions; the human gets some comments, a README that went stale months ago, and a wiki nobody opens. Workbooks start from the opposite idea: write for the human first, and let the machine read the same document. That idea is old, it has a name, and it turns out to be exactly what you want in a world where an AI agent is reading and writing your code alongside you.

Knuth

In 1984 Donald Knuth described literate programming: a program should be a piece of literature. You write an explanation a person can follow — in plain prose, in the order that makes sense to a reader — and the runnable code lives right there inside the explanation. The prose and the code are not two artifacts that drift apart. They are one document. The compiler pulls the code out; the reader follows the prose.

Knuth's point was that a program is mostly read, not written, so the writing should be aimed at the reader. A .work file is a literate document in exactly this sense: paragraphs narrate, and do … end blocks run.

The agent turn

Here is what changed. For forty years "the reader" meant another developer. Now the reader is also an agent — and the agent doesn't just read your code, it writes it.

When a machine is editing your codebase, the prose stops being decoration. It becomes the shared context that you and the agent both work from: what this is for, what must stay true, what to leave alone. A literate document co-locates the three things that usually live in three different places —

• intent (the prose: what you're trying to do and why),
• execution (the code: what actually runs),
• review (both at once: you read the reasoning next to the change).

An agent can read the intent, make the change, and you can verify it without hopping between a ticket, a wiki, and a diff. The document is the program is the spec.

What agent harnesses get wrong

Two failure modes show up the moment you point an agent at a real codebase.

Detached docs. The conventional wisdom says code and documentation should live apart — code in the repo, docs in a wiki, design notes in a folder of Markdown files. With a human team you can just barely keep those in sync. With an agent you cannot. The agent reads the code and the scattered docs as separate, often contradictory sources, and every gap between them is a place for the code to go fuzzy. The more you separate the explanation from the thing it explains, the worse the agent does. (We feel this so strongly that the first thing we did when writing these docs was delete a pile of stale Markdown that no longer matched the code — detached docs are a liability, not an asset.)

Lines-of-code buildup. Agents are eager. Ask for a change and you tend to get more code — another file, another layer, another abstraction "to be safe." Do that for a few weeks and you have a thirty-thousand-line codebase where nobody, human or machine, can hold the whole picture, and every edit risks drift somewhere far away. The fix is not a bigger context window. The fix is to force simplification: let the agent write its reasoning next to its code, and a simpler path almost always appears. Prose is where you notice that three functions are really one.

Why Elixir

If you're going to be opinionated about writing less, simpler code, you should be opinionated about the language too. We chose Elixir.

Elixir is easy to read. You can hand a block of it to someone who has never seen it and they'll mostly follow along — it reads close to plain instructions. It's easy to learn and genuinely capable as a server-side language. We picked it for two concrete reasons: its concurrency model (lightweight isolated processes, the BEAM) is a perfect fit for running many workbooks and agents side by side, and it fit the architecture we needed rather than fighting it.

And because a .work block can be written in Elixir, you get the full language — this really is Elixir, written inside a literate document:

def greet :hello do
  def run(name), do: "hello, #{name}"
end

We were inspired here by org-mode and MDX — both wonderful ways to mix prose and live content. We wanted to go further: deeper language concepts, and the ability to manage real parts of the codebase directly from these blocks, not just illustrate them.

Radical simplicity

There's a piece we keep coming back to, Radical Simplicity. Its argument: developers are happiest, and software is best, when you stop drowning in glue code and framework churn and get back to solving the actual problem — with one database, one language, as little machinery as possible.

That's the same instinct, pointed at the agent era. Microservices and serverless sprawl don't just cost money at scale; they give an agent a hundred moving parts to keep consistent. Collapse the stack — one engine, one language, the document and its code in one file — and you give both the human and the agent something small enough to actually understand. Literate programming is the writing style. Radical simplicity is the discipline. Together they're how you keep an agent-built codebase from turning into the thing everyone's afraid of.

Why WebAssembly

A literate document that mixes languages needs a common ground to run the foreign-language blocks on — one target they can share. That target is WebAssembly. It's also the thing that lets us run many agents safely at once. Two properties, both load-bearing.

One target for foreign-language blocks

If the promise is "write a block in the language that fits, in one document," you need a common target the foreign-language blocks can share. WebAssembly is exactly that: a small, portable instruction format. Today Rust, C, C++, Zig, and Swift compile down to it. Instead of gluing a dozen runtimes together, those blocks compile to the same thing and run in the same place.

Not everything goes through WASM, by design. Elixir server units run natively on the BEAM — they don't compile to wasm. And a client block's body is emitted into the page as a browser island, which is its own lane. WASM is the target for the foreign-language blocks; the BEAM and the browser-island lane handle the rest.

WASI — the WebAssembly System Interface — extends that with a standard, portable way for those modules to touch the outside world: files, clocks, the network. One interface for the languages that compile to it. That's what makes the .work promise of "the language that fits" actually buildable.

Isolation is the other half

WebAssembly modules run sealed off — from each other and from the host — by default. A module can't reach memory, files, or network it wasn't explicitly handed. That isn't a nice-to-have here; it's what lets the Nexus run many agents and tenants side by side. Each agent's code runs in its own sandbox, granted only the capabilities it needs.

Sandbox per request, not per second

This changes the economics of running agents. The usual approach keeps a Linux container or VM running per agent, billed per second — even while it does the same operation over and over. WebAssembly sandboxes are cheap enough to spin up per request: instantiate one, do the work, throw it away. For agent workloads — often the same operation many times — that's dramatically cheaper and scales to far more concurrent agents than keeping warm Linux boxes around. It's the same scale-by-RAM story, applied to agents.

The honest caveat: speed

WebAssembly's tradeoff is build time. To run a block it must be compiled to WASM first. So you either pre-build your packages, or — for things compiled dynamically at run time — cache the result after the first run and reuse it. In practice you acknowledge what your users and agents actually do, pre-warm or cache those paths, and the first-run cost is paid once. The only real caveat is speed, and it's addressable: caching, a build queue, and languages that adopt WASM well. Zig has been the smoothest of the bunch.

Standing on others' work

We don't run our own engine — workbooks run on wasmtime (via wasmex, its Elixir binding), from the Bytecode Alliance. The portable system interface is WASI, stewarded by the Bytecode Alliance and the W3C. And the wider ecosystem — the people behind WASIX at Wasmer, and the broader WebAssembly community — is what makes "every language, one interface" practical at all. Workbooks is an integration of that work, not a reinvention of it. Credit where it's due.

What is a workbook

A workbook is the woven artifact — the single, self-contained thing you ship and run. You author a folder of .work files; the work CLI weaves that folder into one workbook, and a Nexus runs it (or a browser opens it). The folder is the source; the workbook is the product.

Source vs. workbook

It's worth keeping the two apart, because they're easy to blur:

• The source — a folder of .work files (plus any assets). This is what you write, read, and version: a tree of literate documents, prose and do … end blocks side by side. It's the authoring surface, not the thing that runs.
• The workbook — what work weave compiles that source into: one shippable, self-contained artifact. This is the end product — the thing a Nexus serves and a browser can open.

The relationship is the familiar one between source and build: you edit a tree of files; a build step folds them into the thing you actually ship. Here the build step is the weave, and its output is the workbook.

How it's woven

You never assemble a workbook by hand — the CLI does it from the source folder:

work weave <dir> <out>   # fold the .work tree into one workbook
work check <dir>         # resolve refs + audit what each block may do
work dev <dir>           # watch the folder and re-weave as you edit

work weave reads the whole tree, resolves the links between files, and emits a single artifact. work dev does the same continuously, re-weaving on every save and hot-swapping the result into a running Nexus, so the live workbook tracks your edits.

That artifact is HTML — but HTML here is purely a build output, the format the weave emits because it runs everywhere. You don't author or configure it and you never hand-write it. You write .work; the weave produces the workbook.

What you put in the source

Everything you write in the source .work files falls into one of four lanes — you'll meet them properly in Anatomy of a .work file:

• Prose — the rich text that narrates and carries links between ideas.
• Declaration — structure with no body: a table, an enum, a record.
• Code — a runnable block: a function, a server unit, a browser island.
• Placement — the first word of a block says where it runs: in the browser (client), on the engine (server), or in a capability sandbox (sandbox).

One file can hold all four. That's the point — the thing people see, the code that makes it work, and the data it stands on don't live in three repositories. They sit together in the source, and the weave carries them into one workbook.

Why a single artifact

Because a workbook is one woven thing, it moves the way a finished document moves: you deploy it to a Nexus, open it in a browser, or hand it to someone — and they get the whole piece of software at once, interface and logic and data shape together. The source stays legible for authoring and review; the workbook is the compiled result that actually runs.

Kits and apps

Most workbooks are one of two things. A kit is meant to be imported and composed by other workbooks — a shared piece other things build on. An app is the leaf you launch — the thing with an interface you actually open. A workbook can be both: an app that also exports a kit for the next one to use.

You don't have to decide this up front. Write a .work file, weave the folder, and you have a workbook — head to What is a .work file to see what goes in the source.

What is a .work file

A .work file is a literate document: plain prose with runnable blocks mixed in. The prose explains; the blocks run. It is not a new programming language — it's a way to write literate source in the languages you already use, with the explanation living right next to the code.

Prose narrates, work blocks run

Open any .work file and you'll see two things. Prose — ordinary paragraphs that explain what's going on, aimed at the reader. And work blocks — the runnable pieces. A work block opens with a header and ends with end:

server greet :hello do
  def run(name), do: "hello, #{name}"
end

That's the whole format: prose for the reader, work blocks for the machine. Every work block header reads the same way — <kind> [lang] :name … do … end — where the first word, the kind, says what the block is and where it runs. Three kinds carry most of the work, and each does something distinct.

server — runs on the Nexus

A server block runs on the Nexus, on the BEAM. It's your backend: logic, data access, anything that needs to happen on the engine. Here it's Elixir:

server orders :place do
  def run(order), do: Store.create(Order, order)
end

This is where persistence and trusted work live — the server holds the powers a browser shouldn't.

client — runs in the browser

A client block is a browser island. Its body is the interface, rendered into the page and run in the browser. This is the part people see and touch. Here's one in a .work file:

  client :counter do
    <button class="demo-btn"
      onclick="this._n=(this._n||0)+1;this.querySelector('b').textContent=this._n">
      Clicks <b>0</b>
    </button>
  end

And here is that same block running — emitted into this page, no build step you wrote, no separate file. Click it:

Same file, different home: the server above runs on the engine, this client runs in the browser — and they sit side by side in one document.

sandbox — runs in a capability box

A sandbox block runs untrusted or risky code in a capability-scoped box: compiled to WebAssembly and given only the powers you grant it. Perfect for a scraper or a snippet an agent wrote. You name each power in the header's grant: list:

sandbox :scrape, grant: [fetch] do
  extern char* fetch(const char* url);
  char* run(const char* url){ return fetch(url); }   // the host brokers the call
end

The sandbox can compute and do exactly what it was granted — nothing more. Three kinds, three places code can run, all written the same way.

Any code can be a work block

Those three are the placements you'll reach for most, but the bigger point is that a work block's body is written in a real programming language, not a new one. Elixir runs native on the Nexus (the BEAM). And these compile to WebAssembly today:

rust · c · cpp · zig · swift

A Rust function, a Zig routine, a C++ kernel — drop it in a work block and it compiles. More languages are recognized but not yet compiling (python · go · js · ts · svelte · solid). The literate document is the authoring surface; the code inside is whatever fits the job.

It's a real tree, not text matching

One quiet but important detail: a .work file isn't parsed by guessing with regexes. The do … end block is the delimiter, and each work block parses into a real syntax tree — kind, language, name, and body all read off the structure. That single parse is shared by everything that touches the source: the viewer that highlights it, the tool that maps dependencies, and the check that audits capabilities. One source of truth, read the same way every time. (More on the header in Block grammar.)

index.work — it all compiles together

A workbook is rarely one file. You write several .work files, and one of them — index.work — is the composition root that names the project and lists its pieces in order. The weave reads from the index and folds the whole tree — every page, every work block, across every file — into one compiled workbook: the single artifact a Nexus runs or a browser opens.

So the arc is: write prose and work blocks in .work files, compose them in an index.work, and weave it all together into one workbook. Next, see the four lanes up close in Anatomy of a .work file.

What is the Nexus

The Nexus is the engine you own. It runs your workbooks — on your Mac, on a server, or in the cloud — and connects them to your data, your services, and each other. A workbook is the thing you build; the Nexus is the thing that runs it.

One command, dev is prod

One command starts the Nexus and it serves your workbook. There's no separate "production setup" to graduate to later. The engine you run on your laptop while you're sketching is the same engine that runs the finished product at scale — dev is prod. The prototype becomes the deployment without a rewrite.

You'll find the exact command in Running the Nexus.

Everything runs isolated

Inside the Nexus, every moving part is its own isolated process — each agent, each tenant, each piece of running code. This comes from the BEAM (the runtime behind Elixir, originally built to keep phone networks up), and from running untrusted code inside WebAssembly sandboxes. An agent can build, run, and rebuild inside that boundary without ever reaching your keys, your files, or anyone else's work.

The same engine backs all the lanes of a workbook: the server units that run on it, the agents, the data, sync between clients, and the compile/weave step that turns .work files into running software.

The economics: scale by RAM

Here's the part that matters when you do the math. The usual way to build for scale — microservices and serverless — costs an arm and a leg as you grow: every service is a deployment, every function call is billed, and the glue between them is its own tax.

A workbook on the Nexus scales differently. Because everything runs as lightweight isolated processes inside one engine, you scale by memory — give the Nexus more RAM and it holds more. That is dramatically cheaper than scaling out a fleet of services, and it's a single system to reason about instead of a maze.

And it's multi-tenant capable. By default the Nexus runs single-tenant, which is all most workbooks need; flip tenancy-mode to multi (with a Postgres database and real auth) and the same engine isolates tenants — no rewrite, no separate production stack. The thing you build on day one runs the way it will run at scale.

This is radical simplicity applied to the runtime: one engine instead of a microservices maze.

Yours to run anywhere

The Nexus is portable — a Mac, a Linux box, a VPS, or the cloud, on your own account. You choose where it runs, and it carries the whole journey with it. See Deploy: local and cloud for the two canonical targets, or Workbooks Cloud if you'd rather we run it for you.

What is the work CLI

work is the one Workbooks command line — author, build, run, deploy. It operates on a folder of .work source: it reads the tree, weaves it into a workbook — one shippable artifact — and stands up a Nexus to run it. The same work binary runs natively on your machine and inside the wasm agent sandbox, so an agent has the exact tools you do.

The lifecycle

Working on a workbook follows a simple arc, and each step is one command.

You author — write .work files, then work check to make sure every reference resolves and every block only does what it's allowed to. work structure lists the units in the tree so you can see what you've got, and work why, work near, and work wit answer questions about how blocks depend on each other.

You build — work weave folds the whole folder into one self-contained HTML artifact. While you're iterating, work dev watches the folder and re-weaves on every change (and hot-swaps into a running Nexus), so the page updates as you type.

You deploy — work deploy stands up a runtime, local or cloud, from declarative settings that live with the workbook: scaffold them, validate, apply.

That's the loop: author → build → deploy, all over the same folder.

Command reference

The CLI groups its verbs by what you're doing.

Author — read & verify a tree

Build — weave & run

Deploy — stand up a runtime

Platform — identity & contexts

Run work help to see the live surface.

For the deploy story end to end, see Deploy: local and cloud.

What is Workbooks Cloud

The Nexus is yours to run anywhere. Workbooks Cloud is us running it for you — a managed Nexus with a portal in front of it, so you can ship a workbook without standing up any infrastructure yourself.

A managed Nexus + a portal

Cloud is the same engine described everywhere else in these docs, hosted and kept running on your behalf. The portal is where you manage it: you work inside a Nexus (your isolated unit, roughly an organization — cloud or local) and organize work into workspaces under it. You deploy a workbook, it runs, and the data, storage, and scaling are handled for you.

When to use Cloud vs running it yourself

Reach for Cloud when you want the workbook live without thinking about servers — the fastest path from work weave to a URL.

Run it yourself when you want the Nexus on your own machine or your own cloud account — see Deploy: local and cloud. Nothing is locked away: the engine is the same in both places, so you can start on Cloud and move to your own infrastructure later, or the reverse.

There's also a middle path — bring your own infrastructure. You can point a managed Nexus at your own storage and database and pay for compute only, instead of handing us the whole stack. Same engine, your backend.

What it costs to reason about

Workbooks Cloud is priced around what you actually use — storage and compute — not per seat, so adding people doesn't change the bill. Because a workbook scales by memory rather than by spinning up a fleet of services, the cost curve stays far flatter than the usual per-service, per-seat stack.

Open the portal

The portal is where you sign in, create a Nexus, and deploy. Start at workbooks.sh.

These docs stay deliberately conceptual about Cloud. The portal's own screens — workspaces, members, billing, storage — are documented in the portal itself, where they're always current.

One frontend, many targets

Workbooks runs on desktop, in the browser, and on mobile. There is no separate desktop app, web app, and mobile app — there is one frontend that talks to a single capability surface. A target is just a choice of how that surface is fulfilled. No code fork per platform.

The single seam

The UI never calls the operating system, the network, or the runtime directly. It calls one set of named capabilities — open a file, fetch a URL, run a unit — through a single membrane: the Host (the Dock seam). Behind the membrane a router decides who fulfills each call. That is the whole architecture: the app asks for a capability; a provider supplies it.

Providers fulfill capabilities

Every capability is satisfied by a provider. There are two kinds:

• local — served on the device: the OS through a native shell, or the browser's own APIs. Reading a local file, showing a native dialog.
• runtime — served by a shared nexus over the wire, via RCP. Server units, data, sync, the compile-and-weave lane.

A target — desktop, web, or mobile — is a routing config: which capabilities go local, which go to a runtime, and which runtime endpoint to use. Swap the config and the same frontend runs somewhere new. The UI is never recompiled for a platform; it is re-pointed.

Where the lanes run

This mirrors the placement model:

• a client island renders client-side — wasm in the browser, so it runs on every target with no special engine;
• a server unit, agents, data, and the compiler lane are backed by the runtime provider.

The browser is a render target, not a second runtime contract the UI has to manage. There is one Host surface; targets route it differently.

Why one seam matters

The trap every cross-platform tool falls into is a second contract: the UI ends up knowing about both an OS API and a server API and managing the difference. Here the UI knows exactly one thing — the capability membrane. Local versus runtime is the router's problem, not the app's. That is how desktop, web, and mobile stay one codebase instead of three that drift apart. The handshake that lets a client discover and connect to a runtime is Runtime connect (RCP).

Runtime connect (RCP)

When a client — desktop, web, or mobile — uses a nexus as its runtime provider, it first has to learn what that runtime is: which protocol it speaks, how to authenticate, what it can do. RCP is that handshake — a small, public description a runtime serves about itself.

A self-describing runtime

Every nexus answers a well-known discovery endpoint with a compact description of itself. A client fetches it once and knows how to connect — no out-of-band config, no guessing. The response covers:

• protocol version — which RCP revision the runtime speaks;
• runtime version — what build is running;
• tenancy — single- or multi-tenant;
• auth — how to authenticate: a trusted rung for a local runtime, or OIDC/JWT with an issuer and key set for a shared one;
• transports — which wire protocols are available (HTTP, plus websockets when offered);
• capabilities — which planes this runtime exposes.

The capability planes

A runtime advertises what it offers, so a client only attempts what is actually there:

• data — the workbook data plane: serving workbooks, their resources, and routes. Every runtime has this.
• platform — the control-plane fleet API, present only when a runtime runs as a control plane. A plain single-workbook runtime does not advertise it, and a client does not try to use it.

Because the runtime declares its planes, the one frontend adapts to whatever it connected to instead of assuming a fixed server shape.

Names, not URLs

You point at a runtime by name, not by pasting an RCP endpoint: work nexus <url> targets an engine, work login authenticates against it, and the tooling runs discovery. The name resolves to a runtime your account owns; RCP fills in the rest. (See What is the work CLI.)

Why a handshake at all

A client that hard-codes its server's shape breaks the moment the server changes, and cannot tell a local runtime from a cloud one. RCP makes the runtime the source of truth about itself: auth rung, tenancy, and planes are discovered, not assumed. That is what lets the same client connect to your laptop's runtime today and a cloud nexus tomorrow with no code change.

The elastic build tier + the compile cache

A nexus runs heavy build work — compiling packages to wasm, running per-tenant CI/CD — off its serving path, on ephemeral Fly Firecracker workers. A content-addressed compile cache turns "compile on every deploy" into "compile once, fetch forever." This is the design; it is not built yet. Tracking: the build-tier epic.

The gap this fills

A nexus already runs wasm sandboxes, but it also has to produce them. Today the compile lanes (rust/c/zig/js → wasm component) run inside the serving nexus: a single 450–900 MB wasmtime compiler process, ~7–20 s, shelled on the same box that serves pages and runs agents. On a 1 GB Starter machine that compile competes with everything else for RAM, and a cold package is recompiled from scratch every time anyone needs it. Two problems — placement (heavy work on the serving box) and waste (recompiling identical inputs) — and both have the same fix: move the work out, and never do it twice.

The fourth compute mode: a job

The runtime has three compute modes. The build tier adds a fourth.

A job is one isolated unit of heavy work: it runs on an ephemeral Fly Firecracker microVM the nexus dispatches, returns an artifact plus logs, and disappears. It is per-tenant, billed per-second, and scales to zero. It differs from sandbox precisely because sandbox must stay light and live — a job is allowed to be heavy and slow because it never touches a request.

You do not hand-write a job block in the common case: the compile lane emits one automatically when a compile is heavy or a cache miss needs filling. You do write jobs explicitly for CI/CD pipelines (below).

Two workloads, metered separately

The tier carries two workloads whose costs differ by ~600×. They must never share one "build-minutes" bucket.

• (a) Compile offload — short, bursty. Shape: shared-cpu-2x / 2 GB, ~15 s active. ~$0.0001 per compile (compute-seconds dominate once the image isn't re-pulled).
• (b) In-nexus CI/CD — longer pipelines (build → test → publish). Shape: performance-4x / 8 GB, ~10 min. ~$0.05 per run (compute plus modest egress).

This is GitHub Actions, native to the nexus and per-tenant: the workflow lives in .work, runs on your fleet, and publishes wasm components / images back into the nexus. Per-second Fly billing beats GitHub Actions' per-minute rounding badly for short compiles (a 15 s compile on GHA bills a 1-minute minimum, 60× our cost), and a 10-min CI run on performance-4x is both cheaper and beefier than a GHA 2-core runner.

The orchestration already exists

The trigger layer is the reactive + time layer already shipped. Nothing new is needed to fire a build:

• a #event on the bus, a git push (the nexus is a git remote), or a hook's trigger (cron/every/org-timestamp) →
• runs a flow whose steps are jobs on workers →
• which publish artifacts (wasm components, images) the serving nexus consumes.

"Rebuild my wasm library on every push to this subtree" or "recompile nightly" are just a hook plus a flow over jobs — no new authoring surface.

The compile cache — "compile once per nexus, then fetch forever"

This is the lever that makes the whole tier cheap. wasm compilation is deterministic: the same source, toolchain version, and flags always produce the same artifact. So it is naturally content-addressable — and a content-addressed artifact is tamper-evident by construction: the key IS the hash of the bytes, so a corrupted or substituted artifact fails its own hash. This is the Nix binary-cache / Bazel remote-cache idea, applied to wasm.

The key

key = blake3( normalized_source ⊕ lane ⊕ toolchain_version ⊕ flags )

A compile request computes the key first. Hit → fetch the prebuilt .wasm from storage (~$0, just egress, no worker spun). Miss → dispatch a compile job, store the result under the key, then serve it. Most "compiles" become a fetch.

Two scopes — the security boundary

The cache has two namespaces, and the boundary between them is the whole security model:

• Shared package cache (public, global). Public dependencies — an npm package, a crate, a Go module compiled to wasm — are the same artifact for everyone on the same version. The first tenant who needs [email protected] → wasm pays the one compile; every other nexus, forever, gets a cache hit. This is a wasm equivalent of a package registry's prebuilt-binary cache. Safe to share because it is content-addressed: you can only ever read back the exact bytes whose hash you asked for. Artifacts are signed for provenance on top of the hash.
• Private tenant cache (per-nexus). A tenant's own source compiles to artifacts that are theirs alone. These live in a tenant-scoped namespace, never the shared one, encrypted at rest, reachable only by that tenant's nexus. A tenant's input hash can never promote an artifact into the public cache — the scope is decided by the source's origin (declared public dependency vs. tenant subtree), not by the key.

The backing store: Tigris (objects) and Fly Volumes (blocks)

The cache uses two distinct storage homes. They are different products with different shapes and different jobs:

• Tigris is the artifact store — the "cold wasm storage." Tigris is a separate company, Tigris Data, providing globally-distributed, S3-compatible object storage. It is offered through Fly as a storage partner (fly storage create) — it is not Fly's own product. It fits a global shared cache: low-latency access from Fly machines, with objects auto-replicating near where they are pulled, so a package compiled once is cached close to every nexus that later requests it. The content-addressed artifacts (both scopes) live here as S3 objects, keyed by their hash.
• Fly Volumes are Fly's own region-pinned block storage — a volume attached to a single machine in a single region. This is where per-machine local state lives: the serving nexus's tenant SQLite / WB_DATA mount (the same store used for Litestream and tenant DBs), and a build worker's baked compiler rootfs. Volumes are machine-local, the right home for hot per-instance state and the wrong home for a global artifact cache.

A small hot index (key → object) lets a hit skip the Tigris round-trip entirely. The index is nexus state and the cache config is a .work deploy block read via Nexus.Config — no JSON sidecar.

What the cache does to the economics

The per-compile cost in the pricing model is the cost of a miss. With a healthy shared-cache hit rate, the fleet only ever compiles the long tail of genuinely-new inputs; common packages are compiled once across the entire customer base and fetched thereafter. The compile tier's real cost tracks cache misses, not compile requests — which is what makes a generous compile allowance in even the free tier viable.

Security & isolation — the cache must not leak or be poisoned

Two attacks define the design: confidentiality (does a shared cache leak one tenant's private code to another?) and integrity (can an attacker poison the cache so a victim runs malicious bytes?). Both have clean answers, learned partly from how other build caches failed.

Confidentiality — you can only fetch what you can already name

A content-addressed artifact is addressed by hash(content). To request an artifact you must present its key, and to know the key you must know the content. So you can only ever retrieve an artifact whose source you already possess — the cache hands back nothing you did not already hold. A tenant requesting a public package addresses it by the public registry's published integrity hash (from their own lockfile); they literally cannot name a private artifact whose source they do not have.

That argument does not stand alone. A provenance gate at write time decides the namespace:

• Shared/public admission requires the source to have been fetched from a public registry and its integrity hash to match what that registry published. Nothing else qualifies.
• Everything else — a scoped/private package, a private registry, a git dependency, the tenant's own subtree source — goes to the tenant-private namespace only: encrypted at rest, ACL'd to that one tenant, and never cross-tenant deduplicated even when bytes match (so there is no "is anyone else compiling this proprietary lib?" existence oracle). The shared pool therefore only ever contains already-public-registry content.

Nothing is ever keyed or admitted by package name. A malicious public @acme/[email protected] cannot shadow a private one of the same name — the requester addresses by their lockfile's integrity hash, and admission verifies that hash against the registry the source actually came from. That closes the dependency-confusion class behind recent npm supply-chain attacks.

Integrity — only trusted builders write the shared cache

The instructive failure is CREEP (CVE-2025-36852, severity 9.4): bucket-backed build caches (S3/GCS/R2) poisoned by a first-to-cache-wins race — an attacker produces malicious output from the same input and uploads it first. The lesson is sharp: input-based cache keys cannot prevent this, because the poisoning happens at build time, before any hashing — "correct and poisoned artifacts are identical from a validation perspective." Nix's binary-cache history says the same: a content hash alone is not a trust anchor — artifacts must be signed.

So the write path is gated, not open:

• Tenants never write the shared cache. They trigger a compile; our trusted Firecracker worker, running our pinned, version-stamped toolchain, performs the build and signs the artifact with the fleet key. There is no tenant-supplied-output upload path into the shared pool, so "first-to-cache-wins" is impossible — an attacker cannot write at all.
• Readers verify the signature, not just the hash. An unsigned or wrong-signed artifact is rejected and recompiled.
• Untrusted CI contexts are scoped. A PR / draft / preview build writes only to an isolated, context-scoped cache, never the shared production one — CREEP's "hierarchical write-access" mitigation applied to in-nexus CI/CD: protected refs write the shared cache, untrusted refs write their own branch-scoped cache.
• Determinism audit (defense in depth). Because the toolchain is pinned and wasm compiles are deterministic, a background rebuilder re-compiles a sample of shared artifacts on an independent worker and compares hashes; a mismatch raises a poisoning / non-determinism alarm (the reproducible-builds rebuilder pattern).

Verifiable provenance — signatures over a transparency log (Radicle-pattern)

The integrity model above trusts our fleet signing key. We can do better and make every artifact and every build cryptographically verifiable by anyone, with no central authority to trust — the Radicle philosophy (self-certifying, every action signed, trust from cryptography not from where data lives). Radicle itself is not a blockchain, and neither is this: the same guarantees come from signed records over a hash-linked log, at a fraction of the cost. Three layers:

• Signed build attestations (artifact layer). Every shared-cache artifact carries a signed statement — {source_integrity_hash, lane, toolchain_version+digest, builder_pubkey, output_hash} — signed by the builder key. This is the SLSA-provenance / in-toto attestation shape: Radicle for build outputs. A reader verifies the signature chains to a trusted builder root before accepting the artifact. This is what actually defeats CREEP — a poisoned artifact has no valid attestation from a trusted builder, regardless of matching input hashes.
• A transparency log, not a blockchain (the record). An append-only, hash-linked (Merkle) log of every attestation: tamper-evident, publicly/tenant-verifiable, history-immutable — the guarantees people mean by "on chain," without a chain (Certificate-Transparency / Sigstore-Rekor, and effectively how Radicle's signed history works). This log is the same structure as the billing/provenance ledger below — one append-only signed record serves both audit and metering, making billing non-repudiable.
• Capability tokens for invocation (identity). Each build runs under a signed, scoped capability token (biscuit/macaroon-style, extending the existing wbk_ PAT / Nexus.Auth); the attestation records who invoked it, binding cost to a key rather than an IP. You cannot repudiate a build you signed for.

The store is untrusted by design. Trust lives in signatures plus content hashes, so the bucket's location or operator is irrelevant — a swapped or tampered artifact fails verification no matter who controls the store. The nexus accepts only artifacts whose attestation is signed by a builder key in its own trust root, so the store can inject nothing a builder did not authorize. (Distinct surface, same philosophy: the repo/git side — the nexus is already a git remote — is where the Radicle protocol itself fits, via self-certifying signed repos; an interop target as native auth matures.)

Usage, billing & abuse — airtight by construction

Billing must be admission-controlled, not just metered after the fact, or a tenant can run unbilled or runaway compute.

• Admission control before dispatch. A compile/CI request checks the tenant's remaining allowance (Nexus.Config quota) before a worker is spawned. At zero: queue, degrade to the slow in-process path, or reject — never a silent unbilled run.
• Hard per-job caps. Firecracker enforces a wallclock, memory and CPU ceiling per job; a runaway is killed. A single compile cannot exceed its bounded shape.
• Per-tenant concurrency cap. At most N concurrent workers per tenant — anti fork-bomb.
• Single-flight dedup. 100 concurrent requests for the same cache-miss key spawn one worker, not 100 — both a cost control and an abuse control.
• Submission rate limit + egress cap (the CI artifact-egress line).
• The cache is the primary abuse mitigation. Hits are ~free; only misses cost; and misses are capped + single-flighted. The one pathological case — a tenant forcing endless unique misses (randomized source) — is bounded by the quota backstop and a per-tenant miss-rate alarm.
• Reconciled, idempotent ledger. Metering is nexus state, reconciled against Fly's actual machine-seconds, so we bill reality and never drift over or under. The ledger is runtime state and the quotas are .work deploy knobs — no JSON sidecar.

The fleet — cheapest viable shape

• Baked compiler machine image, not per-job pull. The compiler toolchain is ~7.2 GB. Pulling it per job dwarfs a 15 s compile (~10×) — fatal. Instead bake it into the worker's rootfs once; a stopped worker holds it for $0.15/GB/mo (~$1.08/mo) and resumes in ~1–5 s with no pull.
• Scale to zero, resume on demand. auto_stop_machines + min_machines_running: 0 (already how Nexus.Provisioner builds machine config) — a worker costs only its stopped rootfs when idle.
• Right shape per workload. shared-cpu-2x for compiles, performance-4x for CI. Never one shared size.
• Pin CI artifact output to object storage, never push large image layers back out through Fly egress ($0.02/GB) — egress can rival compute for image-publishing pipelines.
• Reuse the existing seam. Workers are provisioned through the same Nexus.Provisioner / Nexus.Fly machine-create path that already provisions tenant nexuses — not a second control plane.

Tier mapping

Meter two units — compile-jobs and ci-minutes — as .work deploy-block knobs read via Nexus.Config, neutral defaults in the runtime, our real numbers in our DeployKit config (the same THE-LINE discipline as tiers). Indicative allowances against our current tiers (Starter $0 / Team $49 / Scale $199):

Overage (keep ~3–4× margin): compiles ~$1 / 5,000, CI ~$0.015/min (still under GHA on stronger hardware). These numbers assume cache misses are the minority — the shared cache is what keeps cost-to-us this low.

The one cost risk

Idle rootfs × tenant fan-out. $1.08/mo per stopped baked worker is trivial per tenant but linear in tenant count — 1,000 tenants each holding a 7.2 GB worker is ~$1,080/mo of pure idle storage. Mitigations, in order: (1) share one compile-worker app per N tenants with per-tenant sandboxing rather than one image each; (2) garbage-collect workers idle > X days, eat one cold re-bake on the next compile; (3) thin the baked image per-language — pull only the toolchains a tenant's declared languages= needs. Watch this line as tenant count grows; it is the only cost that scales without usage. The compile cache makes (1) easy: a shared worker pool is fine because the cache, not the worker, holds the valuable state.

Build order

1. Compile cache, shared scope first — content-addressed key + object store + hit/miss in the compile lane. This alone removes most recompiles with zero new compute infra (misses still compile in-process for now). Biggest win per unit of work. 2. job primitive + Fly worker — baked compiler image, scale-to-zero, dispatched on a cache miss. Moves the heavy compile off the serving box. 3. Private tenant scope + signing — the security boundary, encrypted-at-rest. 4. CI/CD jobs — flow-over-job wired to hook/push/cron triggers; object-store artifact output; the two metered units in Nexus.Config.

Step 1 is independently valuable and ships first; the fleet (step 2) only pays off once the cache is deciding what actually needs compiling.

Anatomy of a .work file

A .work file looks like a document because it is one. As you read down it, the parser sees a simple sequence of pieces: headings, paragraphs, declarations, and runnable blocks. Those pieces sort into four lanes. Once you can spot the four lanes, you can read any workbook.

Here's a small file with all four in it:

Orders

This page tracks orders and shows them in a table.

data Order do id :int total :money end

server place :submit do
  def run(order), do: Store.create(Order, order)
end

The heading and the sentence are prose. data Order do … end is a declaration. server place :submit do … end is code, and the word server is its placement.

Prose

Prose is the rich text that explains. Paragraphs, headings, lists — ordinary writing aimed at the reader. Prose isn't a comment bolted onto code; it's a lane of its own, and it can carry live references to other parts of the workbook (see The prose lane & refs).

Declaration

A declaration is structure with no body to run — you're describing a shape, not an action. A data block declares a typed table, a list of atoms declares an enum, a record declares a struct. Declarations are how a workbook states what its data looks like. They get their own page: Declarations.

Code

A code block is something that runs. It opens with a header and ends with end, and the body is real code in a supported language:

server place :sum do
  def run(items), do: Enum.sum(items)
end

A server unit, an agent, a browser island — if it executes, it's in the code lane. The def/defp functions you write live inside one of these units, not as a block of their own. The exact header shape is covered in Block grammar.

Placement

Placement is the quiet fourth lane: the first word of a code block says where it runs. client runs in the browser, server runs on the Nexus, and sandbox runs in a capability-scoped box. Same literate file, but each block knows its home. This is what lets one document describe the browser and the server at once — see Placement & languages.

Why this matters

Four lanes, one file. The thing people see (prose + client), the logic that runs it (server), and the data it stands on (data) aren't scattered across a repo — they sit next to each other, in reading order, in a single document. That's the anatomy that makes a workbook legible to a person and to an agent at the same time.

Block grammar

Every runnable block in a .work file is written the same way:

<kind> [lang] :name … do … end

That one line of grammar covers all of it. Let's take the header apart.

The header, token by token

server place :submit do
  def run(order), do: Store.create(Order, order)
end

Reading the header server place :submit:

• kind is the first word — always. It says what the block is and where it runs: server, client, sandbox, data, agent, resource, and others. The parser takes the first token as the kind, no exceptions.
• lang is optional. If a token is one of the supported languages, it's read as the language of the body. Leave it out and the block uses its default.
• :name is the atom that names the block — a token starting with :. It's how other blocks and your prose refer to this one.
• Anything else on the line is the block's arguments, passed through to the body.

So sandbox rust :scrape do is kind sandbox, language rust, name scrape. And client :widget do is a browser island named widget.

do … end is the delimiter

A block opens with a non-indented line that ends in do, and closes with the first end at column 0. Everything between is the body — real code in the block's language. Plain prose never ends in do, so there's no ambiguity about where a block begins.

The body can have its own do … end pairs — an if, a case, a nested function. Keep those ends indented: the block closes at the first non-indented end, so the only end written hard against the left margin is the one that closes the block. Write the language naturally with normal indentation and it just works.

A name without a colon

Some blocks name themselves the way the host language does — defmodule Workbook do declares something called Workbook. When there's no :atom, the parser takes the bare name. You'll mostly use :name, but both are understood.

Why it's a tree, not a regex

This grammar isn't matched with fragile text patterns. Because do … end is the delimiter and the header tokenizes cleanly, each block parses into a real syntax node — kind, language, name, and body are read straight off the structure. That single parse is shared by everything that touches a workbook: highlighting, the dependency graph, and the capability audit. Write the block once; every tool reads it the same way.

Next, the lane that surrounds the blocks: The prose lane & refs.

The prose lane & refs

Prose is a first-class lane, not a comment. It's where you explain the workbook in ordinary language — and where you wire ideas together with live references the tools understand.

It's just markdown

The prose lane is markdown. Headings, paragraphs, bold, italic, inline code, lists, and links all work the way you'd expect. Write naturally; the document reads like prose because it is prose.

References that mean something

Inside prose you can point at other things directly, and the parser picks these tokens out in order:

• [[backlinks]] — a link to another block or page in the workbook.
• work://… — a link across the workbook, addressed by path.
• :atom — a mention of a named block or value (the same :name a block declares).
• @type — a mention of a type.
• #tag — a tag you can group and find things by.

These aren't styling. They're how a workbook knits itself into a graph: when you mention :submit or write [[Order]], that's a real edge the tools can follow — the same edges work why and work near walk when they answer "what depends on this?"

Refs inside code are examples, not links

There's one sensible rule worth knowing: a reference written inside inline code is treated as a syntax example, not a real reference. So a sentence teaching you about [[backlinks]] (in code font, like this) doesn't accidentally create a link. Real references live in the running prose; quoted ones stay quoted. This very page mentions the syntax constantly without tangling itself in links.

Why prose carries the graph

Because references are part of the prose lane, the explanation and the dependency graph are the same artifact. You don't maintain a separate map of how things relate — you write the relationships into the sentences, and the workbook is the map. That's a big part of why a .work file stays legible to an agent: the intent and the connections are right there in the text it's already reading.

Next: the structure lane — Declarations.

Hash notes — the ephemeral lane

There are two kinds of prose in a .work file. The first is durable: it describes the system as it timelessly is, and it's read as documentation. The second is about the change — "I switched this because X broke", "TODO verify on prod", "next: wire the guest shim". That second kind doesn't belong in your documentation, because it goes stale the moment the work moves on. A hash note is its home.

Keeping the two apart matters: prose is trusted. The moment edit-talk leaks into it, the documentation starts to lie. Hash notes give that change-story a place to live where it stays useful — and out of the prose.

The three forms

A hash note is a single line in its own lane. The first character names what it is:

• +# … — a pinned note. It stays expanded on the page (the "desk") and survives sweeps. Use it for in-flight intent the next person should see.
• -# … — a drawered note. On the next sweep it collapses to a ≡<hash> handle: the prose moves to the drawer and a small reference is left in its place.
• ≡<hash> … — a collapsed handle. The note isn't gone — this is a live anchor you can re-expand at any time.

Notes nest by indentation, so a tall stack can roll up under one parent handle instead of cluttering the page.

Nothing is ever lost

Hash notes are lossless by design. A drawered note doesn't vanish — it moves down a ladder, never off it:

desk (expanded in source) → drawer (a ≡<hash> handle + a stored row) → archive (git history)

The ≡<hash> is a short prefix of the commit that swept the note, so the handle is a real git ref — git show <hash> recovers the note even if the drawer row is later evicted. To put a note away you flip +# to -#; to throw one away you have to delete it deliberately, and even then git still has it. The system makes losing context hard on purpose.

Reading them back

From the CLI, the work note family explores the whole note repository — and it's git-backed, so it works without a running nexus:

• work note list — every note across the tree.
• work note grep <text> — search notes by content.
• work note near <file> — notes anchored to a file you're reading.
• work note expand <hash> — re-expand a collapsed handle to its full text.

Agents get the same context automatically: when one is about to edit a file, the collapsed notes nearby are surfaced first — so a caution a previous agent recorded ("don't revert this, it deadlocked the runtime") is read before the mistake is repeated, not after.

Guardrails

A drawered note can graduate from a footnote into an active check. Tag it #guard and give it a /pattern/:

-# #guard read secrets through Nexus.Secrets, never the env /System\.get_env/

Once swept, that note becomes a tripwire: anything scanning a diff against the drawer will fire on a match and surface the original note. The lesson defends the codebase instead of waiting to be re-learned.

When is something a hash note, not prose?

If any of these is true, it's a hash note:

• Subject — it's about the change or decision, not the thing itself.
• Staleness — it'll be false after the next edit ("now uses vfkit").
• Deixis — it leans on now / was / changed / TODO / next / I.

When you genuinely can't tell, prefer the hash note. A note costs almost nothing (it's lossless and re-expandable), but a stale sentence in your prose rots the documentation everyone trusts. Keep prose pure; let the change-story live in the drawer.

Hash notes never reach a woven workbook — they're a tool for the people and agents writing the source, stripped from the shipped artifact. See also the durable lane: Prose & refs.

Declarations

A declaration describes a shape, not an action. Where a code block runs, a declaration just states what something is — the data your workbook holds, the options a value can take, the settings it runs under. It's the structure lane.

Typed tables

The most common declaration is a typed table. You name it and list its fields as field :type:

resource Product do
  name :text
  price :money
  stock :int
end

That declares a Product with three typed fields. A resource is the persisted, queryable kind — the Nexus stores its rows and serves them. A data table is declared the same way.

Because the table is declared in the document, your prose can show it: a show Product directive renders the rows as a table, columns drawn straight from the fields you declared. Until you show a declaration it renders as a plain preformatted block — the table appears where you ask for it.

Enums and records

Two more shapes round it out:

• An enum is a fixed set of options — written inline as a field type, a union of atoms like status :draft | :live. It isn't a block of its own; it's the type of a field inside a data, resource, or record.
• A record is a struct — a fixed set of named fields grouped into one value, the way a defstruct works in Elixir.

Both describe shape: you're naming a structure, not running anything.

Attributes

Single settings are declarations too. An attribute is a flat @name value line — configuration stated in the document rather than hidden in an environment variable. Tunable settings live as attributes (read back through the engine's config), which keeps a workbook's configuration visible and reviewable alongside everything else.

The reserved words

A handful of words introduce declarations and directives, so the parser treats them specially rather than as ordinary prose: data, show, query, type, deps, checks, theme, task, user, grant, route, workbook, and nexus. You'll meet most of them where they're used; the thing to remember is that a declaration is always describing, never doing.

Next: where blocks run, and what languages they're written in — Placement & languages.

Placement & languages

Two things about a code block decide how it runs: its placement (where) and its language (what it's written in). Both are right there in the header.

Placement: where a block runs

The kind word at the start of a block puts it somewhere. Three placements cover the ground:

• client — runs in the browser. A client block is a browser island: its body is the interface, emitted directly into the rendered page so it runs client-side wherever the page loads. This is the lane that draws what people see.
• server — runs on the Nexus, the engine, on the BEAM. This is your backend: logic, data access, the work that shouldn't happen in the browser.
• sandbox — runs in a capability-scoped box. Guest code is compiled to WebAssembly and given only the powers it's explicitly granted, so you can run untrusted or risky work without handing it the keys to everything.

A client block is the clearest to see, because its body renders right where you read it. Here's one written in a .work file:

  client :counter do
    <button class="demo-btn"
      onclick="this._n=(this._n||0)+1;this.querySelector('b').textContent=this._n">
      Clicks <b>0</b>
    </button>
  end

And here is that exact block running, emitted straight into this page — click it:

Same file, but client draws in the browser while server runs on the engine — which is how one document describes the whole application.

Languages: what a block is written in

A block's body is real code in a supported language. elixir runs natively on the BEAM; the rest compile to WebAssembly through the work toolchain:

elixir (native) · rust · c · cpp · zig · swift

You name the language in the header (sandbox rust :scrape, client :counter). Leave it off and the block uses its default. The body is ordinary code — there's no special dialect to learn, just the language you already know, written inside a literate document.

Placement and language are independent

The two choices compose. You can write a sandbox in Rust, a client in the browser, a server in Elixir — pick the placement for where the work belongs and the language for what fits the job. That independence is the heart of the format: one workbook, many languages, each block running in the right place.

Next, a compact tour of every kind: Kinds reference.

Kinds reference

The kind is the first word of a block. Here's the whole vocabulary in one place, grouped by what each kind is for. The header shape is always the same — <kind> [lang] :name … do … end.

Runnable kinds

These execute. Their placement decides where.

• client — a browser island. The body is the interface, emitted into the rendered page so it runs client-side. This is what people see.
• server — a unit that runs on the Nexus, on the BEAM, natively. Your backend logic and data access; the def/defp functions you write live inside it.
• sandbox — guest code in a capability-scoped box, compiled to WebAssembly and given only the powers it's granted. For untrusted or risky work.
• agent — a sandboxed function with a brain: a server-side block defined by its prompt, tools, grant, and limit. It reasons and acts, not just computes.
• toolkit — a wrapped CLI compiled to a wasm command; a capability an agent runs.
• flow — an ordered, runnable sequence of steps (a pipeline / state machine) that threads each step's result into the next, over the effect engine. A parallel do … end group fans steps out concurrently.
• worker — a long-lived, supervised, stateful background process: the GenServer concept as a kind. You write init/0 + tick/1 with every:/restart:; the runtime owns the process and its supervision. See Concurrency & background work.
• hook — a reactive binding: match events on the bus → run effects; the composing partner of flow. A trigger fires it on a schedule instead.

Structure kinds

These declare shape; nothing runs.

• data — a typed table. Declares fields as field :type; render it with a show directive (until shown it renders as a plain preformatted block).
• resource — a persisted, queryable table. The Nexus stores its rows; a show directive renders them.
• record — a struct: a fixed set of named fields grouped into one value.

An enum isn't a kind of its own — it's an inline field type, a union of atoms (status :draft | :live) inside a data, resource, or record.

Directives

These tell the page to do something with a declaration.

• show — render a resource as a table, columns taken from its fields.
• task — a declared task or job the workbook defines.
• design — the brand sheet: a block whose CSS is hoisted into the page head, shaping how the rendered workbook looks.
• check — declared assertions the workbook holds itself to.

Reading a kind you don't recognize

The grammar guarantees you can always parse an unfamiliar block: the first word is the kind, an optional language follows, then :name, then do … end. Even if you haven't met a kind before, you can see what it's called, what language it's in, and where it runs — which is usually enough to follow along.

Concurrency & background work

The Nexus runs on the BEAM, where concurrency is the native model — every request, every process, runs on its own lightweight scheduler. You don't have to reach into that machinery by hand. The .work language surfaces it as vocabulary: you declare what should run concurrently or what should run in the background, and the runtime owns the processes, supervision, and restarts underneath. You never write Task.start_link, GenServer, or a supervisor.

There are three shapes, by lifetime:

• Transient fan-out — do several things at once, gather the results, move on. That's a parallel group inside a flow.
• Always-on, stateful — a long-lived process that holds state and keeps working. That's a worker.
• On a clock — fire on a schedule. That's a hook with a trigger (covered with the reactive layer).

Parallel steps in a flow

A flow runs its steps in order, threading each result into the next. Sometimes the next few steps don't depend on each other — they just all need the same input. Wrap them in a parallel do … end group and they run at the same time, on the same threaded value; the flow gathers their results into a list (in the order you wrote them) and threads that list onward:

flow :research do
  step :scope, run: "scoper"          # runs first; threads its result forward
  parallel do                         # all three run concurrently on scope's result
    step :web,  run: "web_researcher"
    step :docs, run: "doc_researcher"
    step :code, run: "code_researcher"
  end
  step :merge, run: "synthesizer"     # receives the list [web, docs, code]
end

Three researchers that each take a few seconds now finish in the time of the slowest one, not their sum. The runtime spawns the BEAM tasks (bounded and ordered) and collects them; you only declared the shape. A parallel group can also be time-gated like any step — parallel after: "1m" do … end delays the whole group.

Workers — long-lived, supervised, stateful

A parallel group is transient: it spawns, gathers, and is gone. When you need a process that stays alive — a poller, a queue drainer, a cache that refreshes itself, anything holding state across time — declare a worker. It's the GenServer concept as a kind. You write only the lifecycle:

worker :indexer, every: "30s", restart: :permanent do
  def init do
    %{indexed: 0}                     # the worker's initial state
  end

  def tick(state) do
    # …do the periodic work here…
    %{state | indexed: state.indexed + 1}   # return the next state
  end
end

• init/0 seeds the in-process state, once, when the worker starts.
• tick/1 is called every every: interval; whatever it returns becomes the new state, threaded into the next tick. A worker with no every: just holds its state (a daemon you message yourself).
• every: accepts the same durations as the rest of the time vocabulary — "30s", "15m", "1h".
• restart: is the OTP restart policy — :permanent (the default; always restart), :transient, or :temporary.

The runtime starts every declared worker under a supervisor in the nexus tree when the workbook boots. If a worker process dies, OTP restarts it per its restart: policy. A single failing tick doesn't tear the worker down — the error is logged and the worker keeps its prior state, so one bad poll can't kill a daemon (or trip a restart storm). Compiling a workbook only registers the workers; they start on a live, serving nexus — not during a plain check or test run.

Which one do I reach for?

All four are the same idea from different angles: you declare intent in .work; the BEAM runs it. No process bookkeeping leaks into the document.

Next: the reactive layer — hooks, events, and effects.

Elixir in Markdown

When a block runs on the Nexus, it's written in Elixir — and it's the real thing, not a cut-down version. A .work file just lets you write that Elixir inside a literate document. This page is a quick tour so the server blocks you see elsewhere read clearly. You don't need to master Elixir to use Workbooks; you mostly need to be able to read it.

It reads like instructions

Here's a function — the def run(...) body lives inside a server unit. Even if you've never written Elixir, you can follow it:

server greet :hello do
  def run(name), do: "hello, #{name}"
end

def run(name) defines a function that takes a name. The #{name} drops the value into the string. That's most of Elixir's day-to-day shape: small named functions that take values and return new ones.

A few ideas worth knowing

• Atoms are names that stand for themselves, written with a leading colon: :ok, :submit, :hello. You've already seen them — a block's :name is an atom. They're how Elixir labels things.
• Pattern matching lets a function branch by the shape of its input. You can write two clauses of the same function and the right one runs:

server status :check do
  def run(:ok), do: "all good"
  def run(:error), do: "something broke"
end

• The pipe |> passes a value into the next function, so a sequence of steps reads top to bottom instead of inside out: items |> Enum.filter(...) |> Enum.sum().
• Immutability — values don't change in place; functions return new values. This is a big part of why Elixir code is easy to reason about, for you and for an agent: nothing mutates behind your back.

Why Elixir fits here

Two reasons, the same ones from the opener. Concurrency: the BEAM runs huge numbers of tiny isolated processes, which is exactly what a Nexus full of workbooks and agents needs. And readability: the language stays close to plain instructions, so the prose and the code in a workbook speak the same calm dialect.

If you want the full language, elixir-lang.org is the canonical guide. Everything there works inside a .work block — because it is Elixir.

Sandboxing and the Dock

Some code you'd rather not trust with everything — a scraper, a third-party toolkit, a snippet an agent wrote. A sandbox block is how a workbook runs that code with only the powers you grant it. It compiles to WebAssembly and runs against a single, audited host surface called the Dock.

The membrane

WebAssembly has no ambient authority: a wasm module can compute, but it can't open a socket, read a file, or call an API on its own. The only things it can do are the functions the host imports into it. The Dock is that host surface — the one place the Nexus hands real powers to guest code.

Nothing crosses the membrane that you didn't grant. That's the whole security model: not a list of rules the guest is asked to follow, but a wall it physically cannot reach through.

What the Dock can offer

The Dock exposes a small, fixed set of host functions. Guest code never gets the raw power — it gets a narrow, typed call that the host brokers. These are the live host functions a sandbox can call by name today:

• fetch — an HTTP GET the host performs on the guest's behalf. The host runs an SSRF gate first, so a sandbox can't reach loopback, private, or link-local addresses even if it asks.
• complete — a brokered LLM completion. The model key never appears in source; the host resolves it and calls the provider (see Secrets & configuration).
• store / load — an in-memory key/value store (store(key, val) / load(key)).
• cache_get / cache_put / cache_delete — a tiered, durable cache. The guest names only a key; the host binds the namespace.
• now — the host clock; emit — write a line to the host log.

Each host function is WIT-typed: the host declares the exact function signature the guest may import. There's no way to import a power that wasn't wired in.

Behind these live calls sits a broader capability catalog — the named capabilities (net, kv, secrets, fs, exec, and the runtime caps vfs, commands, llm, browse, parallel) and the WIT interface each projects. The catalog is the vocabulary the toolchain reasons about; not every catalogued capability has a live guest entry point yet. net (via fetch) and the brokered LLM (via complete) are live today; secrets, fs, exec, and a tenant-scoped kv are catalogued WIT interfaces without a live guest call.

Why broker instead of allow

Every Dock function is the host doing the work, not the host opening a hole. fetch isn't "raw sockets, please be careful" — it's "ask the host to fetch this URL," and the host applies its own policy (the SSRF gate, allowlists) before it acts. That keeps the dangerous part on the trusted side of the membrane, where it can be audited in exactly one place.

You declare what it needs

A sandbox names the host functions it wants, and the weave checks them: the capability audit runs at weave/build time, matching the host functions a block actually calls against what it grants, so a block that reaches fetch is visible at review time and a block that grants nothing can't surprise you. The grants are part of the source — see Grants & capabilities.

The point: untrusted code is still useful code. The Dock lets you run it, see exactly what it can touch, and trust the wall instead of the author.

Grants and capabilities

A capability is a named power: the ability to make a network call, read a key, run a command. A grant is you handing one of those powers to a block. Together they make the sandbox model concrete — and they live in the source, so they're reviewable like any other code.

The host functions

There is a small, fixed set of host functions the Dock brokers — the powers a block can actually call by name and must grant:

• fetch — perform an HTTP GET (host-mediated, SSRF-gated).
• complete — a brokered LLM completion (the model key stays on the host).
• store / load — read and write an in-memory key/value store.
• cache_get / cache_put / cache_delete — a tiered, durable cache.
• now — the host clock; emit — write a line to the host log.

A block that grants fetch can call fetch; it cannot suddenly also reach another host function. Powers don't bleed.

Beyond the live host functions, the Dock maintains a broader capability catalog — named capabilities (net, kv, secrets, fs, exec, publish, …) and the WIT interface each projects. The catalog is the vocabulary the toolchain reasons about; the host functions above are what a guest can call today. (publish is the agent ship path: it lets an agent export a facet app surface it manages and deploy it to the edge — see Authoring an agent.)

Granting a power

A block requests only what it needs. The default is nothing — a sandbox with no grants can compute and return a value, and that's all. You add a power by naming it in the block header's grant: list, and the weave wires the matching host import into the compiled module:

sandbox :scrape, grant: [fetch] do
  extern char* fetch(const char* url);
  char* run(const char* url){ return fetch(url); }   // the host brokers the call
end

A block that never grants fetch is flagged by the audit if it calls it — the grant is the contract. The grant token is the host-function name (fetch, emit, …), the exact name the audit matches against the block's body.

The audit is the point

Because grants are written down and the one parser reads them off the tree, the toolchain can audit them. The capability audit runs at weave/build time: it matches every host function a block calls against the functions it grants, and an ungranted call is a hard error, not a silent capability.

A reviewer (or an agent) sees at a glance that :scrape reaches the network and the report-renderer doesn't. There's no hidden System.cmd, no smuggled socket — if a block can touch the outside world, the grant says so, in the file, in the diff.

(work check is a separate, faster gate: it resolves [[refs]] and validates auth/route policy. The capability audit is the weave/build's job.)

Least power, by default

The model rewards asking for less. Grant load when you only need to read a value by key, not the network. Grant nothing when the block is pure. The narrower the grant, the smaller the audit, and the easier the block is to trust — which is exactly the property you want when an agent is writing the code.

Next: the powers that are deliberately not on this list, and why — The three walls.

The three walls

Some things a sandbox cannot do, and won't ever do as described — not because we haven't built them, but because the architecture rules them out. We call these the three walls. Naming them is a feature: a wall you can see is more trustworthy than a gap left silent.

Why a wall is honest

A capability model is only as good as its edges. If a system claims it can run anything safely, it's either lying or it has a hole. Workbooks would rather tell you exactly where the box ends. Each wall is a place where the safe answer is "no, and here's the seam you use instead."

Bedrock — no native execution in the guest

Guest code runs as WebAssembly. It cannot fork a process, JIT new native code, or shell out to the host's machine. There is no "just run this binary" inside the box.

The escape is not a hole in the wall — it's a trusted host-service broker. When a sandbox needs real execution, it asks the host through exec, and the host runs a registered command (a toolkit) under its own policy. The dangerous part stays on the trusted side.

Bridge — no browser host inside the runtime

A client island is browser code; it expects a DOM, a window, the browser's JavaScript host. The Nexus is the BEAM — there is no browser there. So you can't run browser-host code server-side by pretending the server is a browser.

The seam is a real headless build on the BEAM when you genuinely need to render without a browser — not a fake window bolted onto the server. Client code runs where clients run: in the page, as wasm.

Forge — the compiler frontier

A .work block compiles to wasm through a real toolchain, and that toolchain has edges. Some languages compile cleanly today; others are still being brought up. When a language's path to wasm isn't ready, that block doesn't ship — it's a forge wall, not a runtime promise that quietly fails.

The honest move is to tell you which lane is solid and which is in progress, so you pick a language knowing where it stands rather than discovering the gap at deploy.

The shape of all three

Each wall has the same shape: a thing that looks like it should work, a reason the architecture says no, and a real seam you use instead — a host broker, a proper headless build, a supported language. The walls aren't apologies. They're the reason you can trust what the box does let through. For what it does let through, see Grants & capabilities.

Resources and the Store

A workbook isn't just prose and logic — it stands on data. There are three ways to declare a shape, and they differ by one question: does it persist? Get that distinction right and the rest follows.

Three shapes, one question

• data — a typed table you render with show. You write rows in the file; it's literal data that lives in the document. See Declarations.
• record — a struct: a fixed set of named fields grouped into one value. It describes a shape you pass around in code. Nothing is stored; it's a type.
• resource — a persisted, queryable table. The Nexus stores its rows and you query them back. This is your database, declared in the document.

The line is persistence. data is in the file, record is in memory, resource is in the store.

Declaring a resource

A resource names its fields with types, the same way a data block does — but it means a table the Nexus keeps:

resource Product do
  name :text
  price :money
  stock :int
  status :draft | :live | :sold_out
end

That last field shows an inline enum: status is one of three atoms. The declaration is the schema; the Nexus provisions storage for it when the workbook runs.

Reading and writing

A server unit is where rows come and go, because persistence is a server power. A route maps a method-and-path to a handler, and the handler writes through the store with Store.create(Resource, attrs):

server :orders do
  route "POST /orders", :create
  def create(req), do: Store.create(Order, req.body)
end

The data plane is part of what a runtime advertises over RCP, so a connected client knows the workbook has queryable data without being told out of band.

Rendering it back

Declaring a resource isn't the same as showing it. The show directive renders a resource as a table, taking its columns from the fields you declared:

One line turns the stored rows into a table on the page — no template, no field list to keep in sync, because the columns come straight from the schema. Change a field in the resource and the rendered table follows.

Why it's in the document

A schema in a migrations folder, queries in a model file, and a table in a template are the same fact written three times, drifting apart. Here the resource is the schema, the server unit is the access, and show is the view — all in reading order, in one file, sharing the one parse. The data is as legible as the prose around it.

Routes and pages

A workbook becomes a site when the Nexus serves it. Most of the time you don't write routes at all — a docs-style app declares sections and pages and the runtime renders the navigation for you. When you need an HTTP endpoint of your own, you declare a route.

Pages come for free

An app composition declares its structure, and the runtime turns that into a routed site — sidebar, clean URLs, deep links — with no front-end code:

app :docs do
  title "Workbooks"
  section "Introduction" do
    page "introduction/what-is-a-workbook"
  end
end

Each page is a .work file of prose; the runtime server-renders it and wires the router. You link pages with text and reload-safe deep links just work. This is the common case — declare the tree, get a site.

Routes for endpoints

When you need a real HTTP endpoint — an API, a form handler, a webhook — declare a route inside a server unit. A route maps a method-and-path to a handler:

server :orders do
  route "POST /orders", :create
  route "GET /orders/:id", :show

  def create(req), do: Store.create(Order, req.body)
  def show(req), do: %{id: req.params["id"]}
end

The path can carry params (:id), and the verb is part of the declaration. A handler takes a request map %{params, query, body, method, path, tenant} — path captures arrive as string keys, so req.params["id"]. The server unit holds both the routes and their handlers, side by side.

Guarding a route

Routes default to whatever the workbook's access posture is; you mark the exceptions. Guards are declared in the workbook's auth policy block — public (no auth) or protect (auth required) — matched against requests by method and path, so the access posture lives in one readable policy rather than buried in middleware. The same guards apply whether a request arrives with a session cookie or a minted token — the token carries scopes and is subject to the same per-route check.

One document, browser to endpoint

A page renders prose, a client island runs in the browser, a server route answers HTTP, and a resource stores the rows behind it — all in the same tree, all read by the one parser. The site isn't a separate app wired to the workbook; the workbook is the site. See how one runtime hosts more than one of them in One nexus, many sites, and how a site renders itself in Site mode.

Site mode

This documentation is a workbook. The sidebar, the routed URLs, the deep links you can reload — none of it is hand-written front-end code. It's site mode: the runtime reading an app composition and rendering the whole tree as a navigable site. The same machinery serves any docs-shaped workbook, including yours.

What the runtime renders

You declare structure — sections and pages — and the platform's site mode does the rest:

• a sidebar built from your section / page declarations,
• clean, history-routed URLs (/section/page), reload-safe so a deep link works,
• server-rendered prose for each page, with internal links via text.

The look is yours — it comes from a brand sheet in your composition root, never from the runtime. The Nexus ships unopinionated plumbing; you supply the title and the theme.

Why render it server-side

Server-rendering the prose means the site is fast, linkable, and indexable without shipping a front-end framework to do routing. The client islands that do need to be interactive hydrate as wasm in the page; everything else is just rendered HTML. You get a real site without writing one.

The same shape, scaled

Whether the runtime serves this one docs workbook or a dozen apps side by side, site mode is the same — one nexus, many sites, each a tree the runtime renders. Declare the structure; the site follows.

Running the Nexus

The fastest way to see a workbook run is the push-to-live loop: point work dev at your folder and keep editing.

work dev .

work dev weaves the workbook once, then watches the tree. Every time you save a .work file it re-weaves the output. You write; the woven artifact stays current. That's the whole loop. (Live hot-swap into a running Nexus — an instant reload without re-applying — is not yet wired.)

What "running" means here

There are two things you might mean by "running a workbook," and they line up with two commands:

• Iterating — work dev gives you the live edit loop above. This is where you spend most of your time: write prose and blocks, watch them come alive.
• Standing up a real runtime — when you want an actual Nexus serving the workbook (local container or cloud), that's work deploy. Same engine, but a durable runtime rather than a watch loop.

Dev is prod

The reason this matters: the engine behind work dev is the same engine you deploy. There's no separate "production mode" to learn later — the behavior you see locally is the behavior you get at scale. You're not building a toy that you'll rewrite for production; you're building the production thing, just on your own machine first.

When you're ready to put it somewhere durable, head to Deploy: local and cloud.

Deploy: local and cloud

When you want a durable runtime — not just the dev loop — you use work deploy. It stands up a Nexus for your workbook in one of two places: local or cloud, and both run the same engine.

The deploy loop

work deploy init local

init scaffolds the configuration. Then:

• work deploy validate — check the config is coherent (the same lockouts catch mistakes before they ship).
• work deploy apply — stand the runtime up.

To mount a workbook into a running Nexus, point work deploy at the folder:

work deploy . --nexus my-nexus

Config lives with your workbook

A deployment is described by a set of declared settings that live with your workbook — version-controlled and reviewable, part of the source like everything else. It is not a JSON file off to the side, and it is not a scatter of environment variables. Secrets are the one exception: they're never written into the config, they're injected from the environment at deploy time — see Secrets & configuration. work deploy init scaffolds the settings; you edit them in place.

The settings you declare:

• engine-place — local or cloud.
• tenancy-mode — single or multi.
• storage — local-fs or s3.
• database — sqlite or postgres.
• auth — trusted, betterauth, clerk, or oidc.

Local

engine-place="local" runs the Nexus in a Linux container on your machine (via krunvm), and it's cloud-identical — the same image you'd run in production. It defaults to local-fs storage and a sqlite database, with a persistent /data volume that survives restarts. This is the closest you can get to production without leaving your laptop.

Cloud

engine-place="cloud" deploys to Fly, under your own account — you set the provider, app, and region. It defaults to s3-compatible storage (such as Cloudflare R2) and a postgres database, so it holds up across scale-to-zero machines.

Same workbook, either target

Because both targets run the same engine, moving between them is a config change, not a rewrite — flip engine-place and re-apply. Start local, go to cloud, or run both. And if you'd rather not manage any of this yourself, that's exactly what Workbooks Cloud is for.

Deploy as an index tree

How a workbook tree declares its own deployment. It's the same composition-as-source idea you already use for the app, extended to how the app ships — no sidecar file, no magic filename, no scatter of environment variables.

The convention

The runtime reads its deploy config from the index.work at the deploy root: at boot it reads $WB_DATA/index.work and takes the deploy declaration it finds there. The convention follows from that: put one deploy declaration in the deploy-root index.work, and that index is the deployable unit — the root of the served tree.

Because the config lives in the source, it's version-controlled and reviewable rather than hidden in a sidecar file or a scatter of environment variables. You make an index and give it a deploy declaration to say "this tree ships as a unit."

The manifest index is not a page

The deploy-root index.work is the composition root and the manifest. It is not served as a / page — surface discovery skips it — unless you deliberately give it a client or server block. It indexes the tree and carries config; the served surfaces are its subfolders.

Surfaces are subtrees — a monorepo

A nexus deploy is a monorepo. Any folder that contains an index.work is a surface — a served workbook — and it is mounted at its path relative to the deploy root. A surface at site/lander/ serves at /site/lander; one at docs/ serves at /docs. The URL follows the folder path (WYSIWYG) — there is no remap layer that makes the served path differ from where the file lives. Move the folder and the URL moves with it.

Routing resolves a request to the deepest matching surface (longest path prefix), so site/lander wins over a shallower site. Nesting is therefore natural: a folder may contain other surfaces, as deep as you like.

Workspaces are declared subtrees

A workspace is an organizational subtree, declared in the manifest's deploy block:

deploy do workspaces=" site | Site | 🪧 product | Product | ☁️ docs | Docs | 📖 " end

A workspace may be a single surface (docs) or contain several (site/lander, site/marketing). Workspaces are declared, not auto-derived from top-level folders — organization is your call, not a side effect of the directory layout. A workspace's id is its subtree path on the volume, and that same id is its git remote (/git/<id>.git) and its dashboard file-tree key — one identity, never drifted.

The simple case

Most workbooks are a single nexus: one root index.work with one deploy declaration. The runtime reads its config straight from that deploy-root index.work at boot — that's the whole model.

Secrets & configuration

There are three kinds of "settings," and keeping them in the right home is the most important thing to get right when you deploy. Here is exactly how it works.

Configuration — not secret

Tunable knobs — concurrency, caching, which search provider to use — live in your workbook's deploy config: the deploy do … end block (see Deploy: local and cloud). It's version-controlled and reviewable, part of the source. Not JSON, not environment variables.

Secrets — never in your source

API keys and tokens follow one absolute rule: a secret never lives in your source. Not in a .work file, not in the deploy config, not committed to git — ever. A workbook ships and is version-controlled, so a key inside it would leak the moment you share or push it.

Instead, secrets are provided to the running Nexus through the environment at deploy time, from a secure source:

• Cloud — Workbooks Cloud includes an encrypted, per-organization secret manager. Values are encrypted at rest (AES-256-GCM), shown masked, and revealed only on demand. You set a secret once in the portal and it's injected into your runtime; the plaintext is never stored in the open and never logged.
• Local — the work secret CLI keeps keys in your macOS Keychain, never in a file. You declare which secrets a workbook needs in a secrets do … end block (names + descriptions, no values — so an agent has full context and zero exposure), then:

work secret set OPENROUTER_API_KEY # prompts; stored in the macOS Keychain work secret list # shows declared secrets, masked (set / unset) work secret schema # emits a varlock .env.schema for varlock run

At run time the values are injected (via varlock) into the environment for that one command — never written to disk, never pasted into a .work file.

The runtime then reads every secret through a single, audited path, so there is exactly one place that knows which secrets exist and nothing reads a key ad-hoc.

Machine identity — deploy injection

A few values look like config but aren't yours to write — the data mount path, the tenant slot. The real test is author-time vs deploy-time: you can't author your own mount path or which tenant you're deployed into, because the orchestrator assigns those at boot. So they're not configuration (you don't tune them) and not secrets (they're not sensitive) — they're facts the deployer hands the running Nexus. Read them where needed; never try to set them in a .work file.

The one rule to remember

• Tunable and safe to read → deploy config (.work).
• A key or token → a secret, injected from a secure store, never in source.
• Identifies the machine → deploy injection.

When in doubt, ask: would I be comfortable committing this to a public repo? If the answer is no, it's a secret — and it stays out of every file you write.

Workbooks Cloud

Deploying yourself puts the Nexus on your machine or your own cloud account. Workbooks Cloud is the managed alternative — we run the Nexus for you, so deploying is just pushing a workbook to a runtime that already exists.

If you haven't met it yet, start with the concept: What is Workbooks Cloud.

When to choose it

Reach for Cloud when you want the workbook live without standing up or maintaining any infrastructure — the shortest path from a folder of .work files to a URL. You skip the work deploy apply step entirely; the managed Nexus is already running.

It's the same engine

Nothing about your workbook changes for Cloud. It's the same engine you'd run locally or on Fly, so you can move between managed Cloud and your own infrastructure later without a rewrite. You can even bring your own storage and database and let Cloud handle only the compute.

Get started

Sign in, create a Nexus, and deploy from the portal at workbooks.sh. The portal's own screens stay documented in the portal, where they're always current.

Get started with your CLI agent

Workbooks is built to be driven by a coding agent — Claude Code, Codex, or whatever you use. The whole format exists so an agent can read intent and write code in the same document. This page is the on-ramp for pointing your agent at Workbooks.

You drive the CLI; the agent works inside the sandbox

You run the work CLI to author, weave, and ship — work check, work weave, work dev. An agent you author runs server-side on the Nexus with its own surface: one bash tool over a sandboxed /work filesystem, with a coreutils base, built-in web access, and any toolkits you write. It computes real answers in the box instead of guessing.

Install the skill

The packaged way to teach your agent the Workbooks workflow is the skill:

npx skills add workbooks-sh/workbooks.sh

That gives your agent the conventions for authoring .work files, running the CLI, and shipping a workbook — so you can describe what you want and let it build.

How to work with it

The loop is simple: describe the outcome, let the agent author the .work files, then review the rendered workbook the way you'd review any change — reading the prose next to the code. Because the document carries its own intent, you review reasoning and implementation together, in one place.

That's the whole point of everything in these docs: the workbook is legible to you and to the agent at the same time. Start by reading what a workbook is, then put your agent to work.

Authoring an agent

An agent is a sandboxed function: a server-side unit whose whole definition lives in one block. Where a server unit runs code you wrote, an agent reads a goal and acts — it reasons, runs tools, reads the results, and loops until it's done. You define what it knows, what it can do, what it may touch, and when it stops — and nothing outside the block is needed.

The five fields

agent :analyst do
  prompt """
  You are a terse data analyst. COMPUTE every number with bash against /work — never
  guess one. When you have the answer, reply in exactly the requested format.
  """

  tools coreutils, web              # capabilities — the kits it may run
  grant fs                          # permissions — the host powers it may use
  limit timeout: 120_000            # guardrail — wall-clock only; turn caps don't exist
  manages "shop"                    # ownership — the `facet app` surface it runs + ships
end

• prompt — the instructions, a """heredoc""" (the encapsulation; nothing escapes, so it can contain quotes, code, markdown). This is the only prose field.
• tools — its capabilities: the kits it's allowed to run in bash (coreutils, web, any toolkit you authored). Declared, not global.
• grant — its permissions: the host powers (fs, net, exec, publish, …) it may use. This is the sandbox boundary, written into the definition. → Grants & capabilities
• limit — the guardrail (timeout, wall-clock milliseconds). Turn counters do not exist in this framework — an agent is bounded by time, hooks, and the money/memory boundaries, never by a step count that guillotines work mid-flight.
• manages — ownership: the facet app surface(s) this agent owns. An app is a PRODUCT managed by its agent — the publish <surface> host capability authorizes against this binding (plus the publish grant and the agent's management posture) before shipping the surface to the edge.

tools/grant/limit are composable Elixir — a value, a list, or a reference to something defined elsewhere. Shorthand: if all you need is a prompt, write the prose straight in the body — agent :x do …instructions… end — and the runtime treats the whole body as the prompt. The four-field form is the canonical one; the shorthand is for a quick brain with default capabilities.

How it's contained

Everything the agent does, it does through bash — and bash is not a host shell. Each command is a wasm kit run in wasmtime against a /work virtual filesystem, so the agent reads and writes only inside /work and runs only the kits in its tools. It can't reach the host filesystem, spawn host processes, or open a raw socket; web access is a brokered, SSRF-gated capability. grant sets the boundary, limit sets the stop — the blast radius of an autonomous agent is its own sandbox. → Sandboxing & the Dock

Running it

agent is a server-side kind — it runs on the Nexus, on the BEAM, where the model and tools live. The runtime drives the loop for you: call the model with bash available → run any command in the sandbox → feed the output back → repeat → stop on a final answer or a limit. To run one from your own code (seeding files, capturing edits), call Nexus.Agent.run/1 with the same fields as the block:

Nexus.Agent.run(
  prompt: "You are a terse data analyst …",
  tools:  [:coreutils, :web],
  grant:  [:fs],
  task:   "How many unique users are in users.csv?",
  seed:   %{"users.csv" => csv}
)
# => {:ok, %{answer: "…", vfs_files: %{…}}}

Declare a reusable agent with the block; define one inline here for a one-off — the field names mean the same thing in both. See it built end to end in A coding agent and fanned out in Agents at scale.

Declared and enforced

The agent's powers aren't just documentation — they're enforced at runtime. tools scopes what its bash may run: a command whose kit isn't in tools is refused. grant gates the host powers — a web command with no web/net grant is refused. limit stops a runaway run at its turn or wall-clock budget. So you review an agent by reading the block — which kits, which host powers — with no hidden prompt, tool registry, or ambient access, and the capability audit checks it just like a sandbox. To add a power, write a toolkit and list it in tools.

Reacting to a run

Tag an agent #event and each run emits an event onto the bus, carrying the agent's other #tags. A hook then matches those events and fires effects — notify, run another agent, or kick off a flow. That's the reactive loop: an agent acts, a hook reacts, a flow sequences — all declared, all in the workbook.

Toolkits

A toolkit is a command you wrap once and call everywhere — a small CLI, written in a real systems language, compiled to WebAssembly, and made available as a command that a sandbox or an agent can run through exec. It's how you extend the box with tools of your own.

A toolkit is a wrapped CLI

The body of a toolkit block is an ordinary command-line program — it reads stdin and writes stdout, the classic Unix shape. The platform compiles it to a wasm32-wasi command module and registers it under its name:

toolkit :upper do
  // summary: uppercase stdin
  #include <stdio.h>
  #include <ctype.h>
  int main(void) { int c; while ((c = getchar()) != EOF) putchar(toupper(c)); return 0; }
end

Once registered, upper is a command. An agent told it has an upper tool can pipe text through it; a sandbox with exec can invoke it. The toolkit is the wasm command behind that name.

Many languages, one shape

The language is inferred from the body — C and Rust compile to wasm commands today, each through its real toolchain. Whatever the language, the contract is the same: stdin in, stdout out. That uniform shape is why a toolkit composes with any other command and why an agent can use one without knowing how it was written.

The same source always yields the same command — a toolkit block compiles to one deterministic wasm32-wasi module behind its name.

Why wrap a CLI at all

Three reasons it's worth the block:

• Reuse — write the command once; every agent and sandbox can call it. No copy-pasted shell snippets drifting apart.
• Containment — the command runs as wasm under the Dock, with only the powers granted. A toolkit is a safe way to give an agent real teeth.
• Legibility — the tool's source sits in the document next to the agent that uses it, parsed by the one parser like everything else.

Toolkits and agents

This is the seam that makes agents useful. An agent that "has a bash tool with a web kit" is really an agent granted exec over a set of registered toolkit commands. You build the kit, grant it, and the agent computes real answers with real tools — inside the wall, every time.

A coding agent

A coding agent is the loop you've watched Claude Code or Pi run: read the repo, make one change, run the tests, read the output, decide what's next — until it's green. Most of that is plumbing: a tool protocol, a sandbox to run commands in, a transcript, a budget, a way to add new abilities. Workbooks ships all of it as primitives, so the part you write is small — and this lesson shows where each piece lives: the brain, where it runs, how it's contained, how you give it new powers, and how you run a fleet.

The brain

An agent is a sandboxed function: the block defines it completely — what it knows, what it can do, what it may touch, and where it stops. Four fields, nothing outside the block needed:

agent :coder do
  prompt """
  You are a coding agent working in /work — a checkout of the repository. Your one tool is
  bash. Work like a careful engineer: read first, change ONE thing, run the tests and READ
  the output, repeat — then stop and summarize. Never guess a result you could run for.
  """

  tools coreutils, git, rg            # capabilities — the kits it may run
  grant fs, exec                      # permissions — the host powers it may use
  limit turns: 40, timeout: 180_000   # guardrails — when it must stop
end

• prompt — the instructions, a """heredoc""" so nothing escapes (it can contain quotes, code, markdown). This is the only part that's prose.
• tools — its capabilities: the kits (coreutils, a toolkit you wrote, …) it's allowed to run in bash. Declared, not global.
• grant — its permissions: the host powers (fs, exec, net, …) it may use. This is what makes it a sandbox — the boundary is in the definition. → Grants & capabilities
• limit — guardrails (max turns, wall-clock) so an autonomous run can't run away.

tools/grant/limit are composable Elixir — a value, a list, or a reference to something defined elsewhere. That's the whole agent; you don't define it twice. (Shorthand: agent :x do …prose… end with no fields is just a prompt — fine for a quick brain.)

Where it runs, and how it's contained

This is the part that matters for trusting an agent with your repo:

• Placement — it runs on the server. agent is a server-side kind: the loop runs on the Nexus (the BEAM), not in the browser. You don't choose client/server per call — the kind decides. A client block would be the UI; the agent is the brain behind it. → Placement & languages
• Sandbox — bash is not your shell. Every command the agent runs is a wasm kit executed in wasmtime against a /work virtual filesystem. The agent can read and write files in /work and run those wasm commands — and nothing else. It cannot reach the host filesystem, spawn host processes, or open a raw socket. The sandbox is the wall; the agent is powerful inside it. → Sandboxing & the Dock
• The web is brokered. Reading or operating the web (fetch, scrape, navigate) goes through a host capability that is SSRF-gated — the guest never gets raw network.

So "let an autonomous agent edit and run code" is safe by construction: the blast radius is one /work sandbox.

Its capabilities are kits — and you can add one

An agent's abilities are its kits: coreutils (the unix base — ls, cat, sed, grep…) and web ship by default. To give the agent a new power, you don't edit the agent — you author a toolkit, a small CLI compiled to a wasm command that instantly shows up in bash:

toolkit :rg do
  // summary: ripgrep-style search — rg <pattern> over /work
  #include <stdio.h>
  // …a real grep/ripgrep in C, compiled to wasm32-wasi…
  int main(int argc, char **argv) { /* search stdin/files for argv[1] */ }
end

Now rg is a command the :coder can run — capability granted, sandboxed like every other kit. That's the model: capabilities are composable CLIs, not bespoke tool definitions. (The sandbox kind takes the complementary path — guest code with explicit grant: net|kv|fs|…] capabilities; see [Grants & capabilities.)

The loop you don't have to write

When the agent runs, the runtime drives the loop for you: send the instructions + task to the model advertising bash → if it calls bash, run the command in the /work sandbox and feed the output back → repeat (think, run, read) → stop when the model answers without a tool call, or the wall-clock budget expires. You never touch the tool-call wiring, transcript, or context-window management.

Giving it a task

The agent :coder block above is the agent; the runtime runs declared agents for you. To drive one from your own code — seeding a repo into /work and capturing the edits — call Nexus.Agent.run/1 from a server. It takes the same fields as the block (prompt, tools, grant, limit), runs the loop, and returns the final answer plus whatever the agent wrote:

server :fix do
  route "POST /fix", :run

  def run(req) do
    case Nexus.Agent.run(
           prompt: "You fix failing tests in /work. Read, change one thing, run the tests, repeat.",
           tools: [:coreutils, :git, :rg],
           grant: [:fs, :exec],
           limit: [turns: 40, timeout: 180_000],
           task: req.body["task"],         # "make the failing date test pass"
           seed: req.body["files"]         # %{"lib/date.ex" => "…", "test/date_test.exs" => "…"}
         ) do
      {:ok, %{answer: summary, vfs_files: files}} -> %{summary: summary, files: files}
      {:error, reason} -> {500, %{error: inspect(reason)}}
    end
  end
end

Same vocabulary either way: declare a reusable agent with the agent block, or define one inline here for a one-off — prompt/tools/grant/limit mean the same thing in both. seed writes the repo into the sandbox; vfs_files hands back the edited files — the diff.

Running a fleet

Because a run is a function call, doing a hundred is a map. Fan a coder across every failing ticket; the BEAM runs thousands of lightweight processes, so they go at once:

server :sweep do
  @coder [
    prompt: "You fix failing tests in /work. Read, change one thing, run the tests, repeat.",
    tools: [:coreutils, :git, :rg],
    grant: [:fs, :exec]
  ]

  def run(tickets) do
    tickets
    |> Enum.map(fn t -> Task.async(fn -> Nexus.Agent.run([task: t.body, seed: t.repo] ++ @coder) end) end)
    |> Task.await_many(:infinity)
  end
end

One agent or a thousand is the same code — only the list gets longer. That fan-out is the agents-at-scale pattern; swap the worker for any job.

What to take away

• An agent is a sandboxed function — prompt + tools + grant + limit, the whole definition in one block. Nothing outside it.
• It runs server-side, sandboxed — bash = wasm kits over a /work VFS, web brokered; grant is the boundary, limit the stop.
• Capabilities are kits declared in tools — add a new one with a toolkit.
• Run it with Nexus.Agent.run/1 (same fields as the block), so scaling is a Task.async map.

Autonomous research

Karpathy's autoresearch is a sharp idea: give an agent a real experiment, let it run overnight. It edits the code, runs a fixed-budget trial, checks whether the metric improved, keeps the change or reverts it, and repeats. You wake up to a log and, with luck, a better result. The move that makes it work: you never touch the code — you write the agent's instructions and let it drive. You program the research org, not the implementation.

That's a precise fit for Workbooks. The experimenter is an agent — a server-side brain whose bash runs and measures code inside a /work sandbox — and "keep what improves, loop" is a tiny server around it. This lesson builds the whole loop and is honest about what the sandbox can and can't run.

The experimenter

The brain describes how to run one honest experiment. Pick a task whose result the sandbox can actually measure — here, lowering the size of a compressor whose candidate is compiled and run in-sandbox (a real, attributable metric), in the spirit of autoresearch:

agent :researcher do
  prompt """
  You run ONE optimization experiment in /work. `codec.c` is yours to edit. `bench.sh` is
  fixed — it compiles codec.c and prints `score=<bytes>` for the test corpus. LOWER is
  better. Form ONE hypothesis, make the smallest edit that tests it, run `bash bench.sh`,
  READ the real score, and report it on the LAST line as `score=<number>`. One variable at
  a time so every delta is attributable; report the number you measured, not hoped for.
  """

  tools coreutils, cc                 # capabilities: edit files + the C→wasm compiler
  grant fs                            # permissions: files only — no network for a trial
  limit turns: 30, timeout: 300_000   # guardrails per trial
end

The agent is fully defined by the block — instructions, the capabilities it may use, the permission boundary, and its stop conditions. Note grant fs with no net: a trial can read and write /work but can't reach the network, so an unattended run can't phone home. The compile-and-run goes through its kits inside the sandbox.

The loop

Around the experimenter sits the org: run N trials, and keep an edit only when the metric actually improves — otherwise discard it and carry the previous best forward. This loop is an ordinary Elixir reduce — for a fixed pipeline that's all you need (a flow block is the declarative option when you want named, reusable steps). Nexus.Agent.run/1 returns the final answer (where the score was reported) and vfs_files (the code left behind), which is all the loop needs:

server :lab do
  # the experimenter, defined inline with the same fields as the agent block
  @researcher [
    prompt: "You run ONE optimization experiment in /work. Edit codec.c, run `bash bench.sh`, " <>
            "READ the score, report `score=<bytes>` on the last line. One change at a time.",
    tools: [:coreutils, :cc],
    grant: [:fs],
    limit: [turns: 30, timeout: 300_000]
  ]

  # Run `rounds` trials; the best code + a log fall out the bottom.
  def run(files, rounds \\ 100) do
    init = %{files: files, best: 1.0e12, kept: 0, log: []}

    Enum.reduce(1..rounds, init, fn n, st ->
      {:ok, %{answer: a, vfs_files: edited}} =
        Nexus.Agent.run(
          [task: "Trial ##{n}. Current best score is #{st.best} — try to beat it.",
           seed: st.files] ++ @researcher    # hand the current best code to this trial
        )

      case parse_score(a) do
        s when s < st.best ->
          %{st | files: edited, best: s, kept: st.kept + 1,
                 log: [%{n: n, kept: true, score: s} | st.log]}

        s ->
          # no improvement → revert: keep the previous best `files`, drop `edited`
          %{st | log: [%{n: n, kept: false, score: s} | st.log]}
      end
    end)
  end

  defp parse_score(text) do
    case Regex.run(~r/score=([\d.]+)/, text || "") do
      [_, v] -> String.to_float(v)
      _ -> 1.0e12                          # a trial that didn't report a score never wins
    end
  end
end

That's the entire research org. seed: st.files hands the current best code to each trial; on success the loop adopts edited, on failure it simply doesn't — the "revert" is just not updating the accumulator. After rounds runs you have the best files, the best score, and a log of what was tried and what stuck. Run it on a schedule and it researches while you sleep.

What runs where (be honest about the wall)

The wasm sandbox runs what compiles to wasm — C/Rust/Zig benchmarks, data crunching, algorithms. It does not run a GPU training job; that's a host workload behind the bedrock wall. The pattern is identical either way — the difference is the experimenter reaches heavy compute through a host exec capability (a trusted broker) rather than running it in-guest. Pick the metric your substrate can actually measure, and the loop is the same.

Tuning the org, not the code

The payoff of programming the agent instead of the implementation: to change the research strategy, you edit prose. Want bolder hypotheses? Loosen the "smallest edit" rule. Want a specific axis chased? Say so in :researcher. Want breadth instead of a hill-climb? Run many experimenters from different seeds at once — the agents-at-scale fan-out — and keep the best across all of them.

What to take away

• You program the agent, not the code — the instructions are the experiment design, the same role as autoresearch's program.md.
• "Keep what improves" is the whole engine — a reduce that adopts vfs_files on a better score and reverts otherwise. Loops are plain Elixir; a flow block is the declarative alternative when you want named, reusable steps.
• Unattended is safe — real edits and runs, contained in a /work sandbox; heavy compute is brokered through a host capability, not run in-guest.

Agents at scale

A "swarm" is one move repeated: split a task into many pieces, run an agent on each piece at the same time, then synthesize. The intelligence is in the pieces; the hard engineering is usually the orchestration — a job queue, a worker pool, a result bus, backpressure, retries. On the Nexus that machinery is the BEAM's day job, so the whole thing is a few lines in a server block, and "five agents" and "five hundred agents" are the same code.

This lesson builds a research swarm — the distilled core of our own Search Swarm — and shows where it runs and what each agent is allowed to touch.

Where it runs

This is a server unit, so it runs on the nexus, on the BEAM. That placement is the whole reason it scales: the BEAM runs thousands of lightweight processes, so fanning out hundreds of concurrent agents needs no pool to size and no queue to configure — Task.async over a list is the scheduler.

The shape

Three steps: one LLM call decomposes the task, one agent runs per sub-question concurrently, one call folds the findings into an answer.

server :swarm do
  def run(task) do
    task
    |> plan()                                  # 1 LLM call → N focused sub-questions
    |> Enum.map(fn q -> Task.async(fn -> worker(q) end) end)
    |> Task.await_many(:infinity)              # every agent runs in parallel
    |> synthesize(task)                        # fold all findings into one answer
  end
end

The list's length is the swarm's size. For an ad-hoc fan-out the pipeline and Enum.map are the control flow; a flow block is the declarative option when the steps are named and reusable.

The worker: grounded, and capability-scoped

Each agent searches, pulls real pages, and answers only from what it read. Its powers are host capabilities, not raw access: llm (model completion) and browse (the runtime's headless browser) are brokered seams — the browser is SSRF-gated, so a worker can't be steered into the internal network, and every model call can be metered.

  defp plan(task) do
    {:ok, %{content: c}} =
      Nexus.Llm.complete([%{role: "user", content:
        "Break this into 8 distinct, focused sub-questions, one per line:\n#{task}"}], [])

    c |> String.split("\n") |> Enum.map(&String.trim/1) |> Enum.reject(&(&1 == ""))
  end

  defp worker(question) do
    # one web-grounded search returns candidate source URLs…
    {:ok, %{annotations: cites}} =
      Nexus.Llm.complete([%{role: "user", content: question}], model: "…:online")

    # …pull the top pages with the nexus browser and answer from their text
    pages =
      cites
      |> Enum.take(3)
      |> Enum.flat_map(fn c -> case Nexus.Browse.read(c["url"]) do
                                 {:ok, p} -> [p.text]
                                 _ -> []
                               end end)

    {:ok, %{content: finding}} =
      Nexus.Llm.complete([%{role: "user", content:
        "Answer from these pages only, and cite them:\n#{question}\n\n#{Enum.join(pages, "\n\n")}"}], [])

    %{question: question, finding: finding}
  end

Nexus.Llm.complete (with :online for web search) and Nexus.Browse.read are the host primitives — the worker just calls them. The annotations are the real URLs the model cited; the agent then reads those pages itself before writing a word.

Synthesize — and pay the real bill

Because every model call goes through one seam, you can ask the provider for the actual cost and surface it — credits charged, not an estimate:

  defp synthesize(findings, task) do
    notes = Enum.map_join(findings, "\n\n", fn f -> "## #{f.question}\n#{f.finding}" end)

    {:ok, %{content: report, usage: u}} =
      Nexus.Llm.complete([%{role: "user", content:
        "Write one cited report answering: #{task}\n\nFindings:\n#{notes}"}], usage: %{include: true})

    %{report: report, cost_usd: u["cost"]}
  end
end

Why it stays small

• No queue, no workers, no bus. Task.async + the BEAM scheduler is the infrastructure — server placement is what makes that free.
• Real tools, brokered and scoped. llm and browse are host capabilities — SSRF-gated, cost-accounted. → Grants & capabilities
• One server unit holds the orchestration. Stream it live to a browser by registering it as a live source; persist each run with a resource.

Swap the worker for whatever the job is — a coding agent, an experiment — and the same fan-out runs it at scale.

Why we author these docs as a workbook

A short post on dogfooding — the docs you're reading are built with the thing they document.

Most documentation sites are a static-site generator, a theme, a pile of Markdown, and a build pipeline that turns the three into HTML. We don't run any of that. These docs are a workbook: a folder of .work files, woven by the same work CLI we ship to you.

One file is the table of contents

The whole site is declared in one composition root — index.work — with an app :docs block. It names the site, picks a theme, and lists the sections and pages in order. The sidebar you see is a direct render of that block. Reorder two lines, the navigation reorders. There is no separate config, no front-matter database, no _sidebar.yml.

Every page is just prose

Each page is a sibling .work file. The first heading is its title; the rest is Markdown. Because a page is a real workbook, when one needs to be interactive — like the Examples explorer, which reads live source out of running apps — you drop a client island in between two paragraphs. The same document is both prose and program.

Why it matters

We have a rule: if we build it, we use it. The site-mode renderer behind these docs (Nexus.Docs) is the same one your work new docs scaffold runs. When it's not good enough for our own documentation, we feel it first — and fix it before you ever see it.

One nexus, many sites

How a single runtime hosts this documentation, the example apps, and your projects — side by side.

A nexus is a host. Not a host for one workbook — a host for as many as you mount on it. The runtime you're reading this on is serving the documentation, the Search Swarm, Brandnana, and a slide deck at the same time, each at its own path, from one process.

Each workbook gets a mount

When the nexus boots over a folder of workbooks, every subfolder becomes a mount at /<name>/. The runtime injects a <base href="/<name>/"> so each app's relative links — live/<source>, data/<Resource>, page routes — resolve under its own prefix and never collide with its neighbours.

Names, not URLs

A nexus has a memorable codename (an adjective-animal handle) and a friendly name you give it. You deploy into one by name — work deploy . --nexus <name> — not by copying a URL around. The name is a handle, not a credential: it only resolves to a nexus your account actually owns.

What this unlocks

It means a documentation site, a marketing page, and three internal tools can live on one runtime you pay for once — the same shape whether that runtime is on your laptop or in the cloud. The Running the nexus page shows how to bring one up locally in a single command.