Deploy Kit is the USER tool: it runs the one runtime OCI image for your own use — locally (a container) or in the cloud (a provider recipe). It is NOT how the platform publishes the compilers package or the runtime image. The bootstrap verb is special: it must run with NO runtime up — it is what brings the runtime up, reading deployment.org and converging via container engine / provider recipe. Native-only.

The three release layers must not be conflated. Deploy Kit is layer 3 (users only). The compilers package (layer 1, published manually) and the runtime image (layer 2, built by CI) are NOT wbx deploy. See Release layers.

The DeployVerb enum (clap subcommands) — cli/src/deploy/mod.rs:31.

Note: the binary is invoked wbx (cli/src/main.rs:24, name = "wbx"). Older docs and source moduledoc comments still say wb deploy; the shipped command is wbx deploy.

Secrets are declared by NAME in deployment.org (#+DEPLOY_SECRETS: KEY …), values staged via secrets set, stored 0600 at <app-dir>/secrets.env (cli/src/deploy/mod.rs:187,206-211), and delivered per provider — env-file locally, the recipe's provider_set_secrets hook in the cloud. Values never enter deployment.org or images (cli/src/deploy/mod.rs:18-21).

The shipped wbx deploy parses deployment.org as flat #+KEYWORD: lines (org_keywords, cli/src/deploy/mod.rs:149). Recognized keys:

WB_IMAGE (env) always wins over #+DEPLOY_IMAGE: = (=cli/src/deploy/mod.rs:127-131). The default image constant is ghcr.io/workbooks-sh/runtime:latest (cli/src/deploy/mod.rs:76).

• init local writes TEMPLATE_LOCAL (#+DEPLOY_TARGET: local, port 4000, OPENROUTER_API_KEY secret) — cli/src/deploy/mod.rs:558.

• init cloud / init fly writes TEMPLATE_FLY (#+DEPLOY_TARGET: fly, #+DEPLOY_REGION: sjc) — cli/src/deploy/mod.rs:570.

There is ONE artifact: ghcr.io/workbooks-sh/runtime:<tag> — the BEAM runtime + wasmtime + litestream + the release, with the in-sandbox compilers pulled in as a separate layer (COPY --from). Every place runs the same image; a target is just a routing config + endpoint, not a code fork.

#+DEPLOY_TARGET: local runs the image in a container on this machine. The engine is auto-detected in this preference order: docker, podman, krunvm (cli/src/deploy/mod.rs:359-361); first one with a working --version wins.

Mounted volumes + env on the container (cli/src/deploy/mod.rs:436-454): <app-dir>/disco → /disco (discovery, WB_DESKTOP_DIR), <app-dir>/data → /data (WB_DATA); env WB_WEB=1, WB_DESKTOP=1, PORT=<port>. After apply, talk to it with wb rt status (cli/src/deploy/mod.rs:464).

krunvm limitation: krunvm cannot deliver the kit's secrets env-file yet — apply bails if secrets are staged. Use docker/podman locally, or a cloud provider. (cli/src/deploy/mod.rs:470-472)

Re-applies are idempotent: docker/podman rm -f the prior container, krunvm delete=s the prior VM, before recreating (=cli/src/deploy/mod.rs:447,473).

Any #+DEPLOY_TARGET: other than local names a provider RECIPE at providers/<place>/bootstrap.sh, which sources the neutral spine _recipe.sh and fills five hooks. Adding a provider = dropping a bootstrap.sh — no recompile (cli/src/deploy/mod.rs:5-11).

Recipe resolution order (cli/src/deploy/mod.rs:279-298):

1. $WB_PROVIDERS_DIR

2. cli/deploy-kit/providers (repo dev, walking up)

3. recipes EMBEDDED in the binary, materialized under the app dir (standalone).

A bootstrap.sh sets WB_RECIPE_PLACE, fills these, and calls wb_recipe_run.

Actions dispatched via WB_RECIPE_ACTION (up | down | status | logs | url | secrets) — cli/deploy-kit/providers/_recipe.sh:53. The engine env every provider forwards is assembled by wb_base_env (WB_WEB=1, PORT, WB_DATA, WB_REGISTRY, plus tenancy / storage / db / secret keys) — cli/deploy-kit/providers/_recipe.sh:33-46.

Fly is the one bundled recipe (personal preference, not privileged — cli/deploy-kit/providers/fly/bootstrap.sh:2-3). Requires fly / flyctl on PATH (:19-21). Deploys either a prebuilt WB_IMAGE or, if WB_FLY_CONFIG / WB_FLY_DOCKERFILE set, a remote build (:52-82). Public URL https://<app>.fly.dev (:88). Lifecycle: fly apps destroy --yes / fly status / fly logs (:90-92). Fly-specific env: WB_FLY_APP, WB_FLY_CONFIG, WB_FLY_DOCKERFILE, WB_INCLUDE_CLIP (:13-14).

On the FIRST cloud apply, the kit generates a 256-bit random WB_PUBLIC_BEARER, persists it in secrets.env, and delivers it to the engine — the control plane rejects requests without it. It is generated ONCE and never rotated (rotation would 401 all live clients). Set WB_ENGINE_TOKEN=<token> to call the engine (cli/src/deploy/mod.rs:406-422).

The OQL kernel (oql.wasm) is a typed WebAssembly Component — pure in / pure out, every export string -> string, no host imports, so it instantiates with no WASI context and any fault traps inside Wasmtime (runtime/kernel/wit/world.wit:6-10). Package workbooks:oql, world oql.

Three distinct layers — Deploy Kit is only layer 3.

Layer-1/2 maintainer functions (NOT CLI verbs; not wbx deploy): Workbooks.Deploy.Image.build/1 (local single-arch, image.ex:31), publish/1 (multi-arch push, image.ex:53), build_compilers/1 (image.ex:80), publish_compilers/1 (image.ex:97).

runtime/host/deploy/config.ex and backend.ex implement a richer model parsed from a :PROPERTIES: drawer (config.ex:29-49), used by the deploy-kit example descriptors in cli/deploy-kit/deployments/:

Coherence rules it enforces (config.ex:56-83): multi tenancy on sqlite is rejected (one writer serializes tenants); multi needs real AUTH; s3 needs STORAGE_BUCKET + STORAGE_ENDPOINT + WB_S3_KEY=/=WB_S3_SECRET env; postgres needs WB_DATABASE_URL env. Secrets stay in the deploy ENV, never the file (config.ex:6-9). See examples cli/deploy-kit/deployments/local.org and cloud-saas.org.

• How-to: deploy/ guides (goal-titled tasks).

• Concepts: the Dock & capabilities · isolation tiers.

• Reference: wbx CLI · Dock capabilities.