The runtime is a standard Mix application. You can run it in three modes: interactive (iex -S mix), as a full server (wb deploy local), or as a one-shot CLI (wb <command>).

The primary development mode. Starts the full supervision tree including the OQL GenServer, the BEAM HTTP endpoint, and the variable store.

cd runtime
iex -S mix

At the iex> prompt you have direct access to every module in the runtime:

# parse a workbook
Workbooks.OQL.parse_headlines(File.read!("my.org"))

# check the build plan
Workbooks.OQL.tangle_plan(File.read!("my.org"))

# render to HTML
Workbooks.OQL.render(File.read!("my.org"))

# variable store
Workbooks.Vars.set("dev", "api_key", "value", false)
Workbooks.Vars.get("dev", "api_key")

The OQL GenServer starts as part of the application. First call to any Workbooks.OQL.* function loads the oql.wasm component via Wasmex. Subsequent calls reuse the loaded component — no per-call startup cost.

Default ports in config/dev.exs:

Override at start time:

PORT=4000 PUBLIC_PORT=4001 iex -S mix

The control plane (port 4000) serves the authenticated API, agent events, and the workbook runtime API. The public plane (port 4001) serves published workbooks by hostname — every request is resolved by the first DNS label of the Host header to a workbook ID, then served as static HTML.

wb deploy local runs the full runtime in a container using krunvm (macOS) or podman/docker as a fallback. It uses the same OCI image as cloud deployment:

wb deploy init          # scaffold deployment.org
wb deploy validate      # check config without running anything
wb deploy local         # build image + run container

This is the canonical way to test deployment config before pushing to cloud. The container is the same image that wb deploy apply ships.

See deployment.org Properties for the full list of config properties.

In iex -S mix, code reloading works the standard Elixir way:

# recompile changed modules
recompile()

The OQL kernel (oql.wasm) does not hot-reload — if you change the kernel Rust source, you need to recompile the kernel and restart:

cd runtime
mix compile              # recompiles oql.wasm if changed
iex -S mix

Run a single expression without the interactive shell:

mix run -e 'IO.puts Workbooks.OQL.render(File.read!("my.org"))'

The desktop app (Tauri) embeds the OQL kernel and runs workbooks locally without any server. It communicates with an optional runtime tier for agents and sync, but viewing and editing workbooks works fully offline. Download from the GitHub releases page.