| name | zio-golem-base-image |
| description | Explains the zio-golem WIT folder structure and how to regenerate the agent_guest.wasm base image. Use when working with WIT definitions, upgrading Golem versions, or regenerating the guest runtime WASM. |
zio-golem Base Image (agent_guest.wasm)
The base image agent_guest.wasm is a QuickJS-based WASM component that serves as the guest runtime for Scala.js agents on Golem. It must be regenerated whenever WIT definitions change.
WIT Folder Structure
golem/wit/
├── main.wit # Hand-maintained world definition (golem:agent-guest)
├── deps.toml # wit-deps manifest — points to golemcloud/golem main branch
├── deps.lock # Auto-generated lock file (gitignored)
└── deps/ # Auto-populated by wit-deps (gitignored)
├── golem-core/
├── golem-agent/
├── golem-1.x/
├── golem-rdbms/
├── golem-durability/
├── blobstore/
├── cli/
├── clocks/
├── config/
├── ...
└── sockets/
main.wit defines the golem:agent-guest world — the set of imports/exports the agent component uses. This file is checked in and maintained manually.deps.toml declares a single dependency source: the golem repo's main branch tarball. wit-deps downloads and extracts the WIT packages from it.deps/ and deps.lock are gitignored — they are populated by running wit-deps from golem/.
When to Regenerate
The base image must be regenerated whenever:
wit/main.wit changes — adding/removing imports or exports- WIT dependencies update — e.g., upgrading from Golem v1.5.0 to a newer version (update
deps.toml then regenerate)
wasm-rquickjs updates — a new version of the wrapper generator may produce different output
The generated agent_guest.wasm is checked in at two locations (embedded in the sbt and mill plugins):
golem/sbt/src/main/resources/golem/wasm/agent_guest.wasmgolem/mill/resources/golem/wasm/agent_guest.wasm
Prerequisites
1. Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-wasip1
2. cargo-component
cargo install cargo-component
3. wit-deps
cargo install wit-deps-cli
4. wasm-rquickjs (pinned to 0.1.0)
The script enforces a specific version of wasm-rquickjs and will refuse to run if the installed version does not match. The required version is defined by REQUIRED_WASM_RQUICKJS_VERSION in generate-agent-guest-wasm.sh.
cargo install wasm-rquickjs-cli@0.1.0
How to Regenerate
From the repository root (zio-blocks/):
./golem/scripts/generate-agent-guest-wasm.sh
The script performs these steps:
- Runs
wit-deps update in golem/ to fetch the latest WIT dependencies into golem/wit/deps/
- Stages a clean WIT package in
.generated/agent-wit-root/ (copies main.wit + deps/)
- Runs
wasm-rquickjs generate-wrapper-crate to produce a Rust crate from the WIT
- Builds with
cargo component build --release targeting wasm32-wasip1
- Installs the resulting
agent_guest.wasm into both plugin resource directories
Fetching Dependencies Only
To update the WIT dependencies without regenerating the WASM:
cd golem && wit-deps
The generation script always uses wit-deps update to ensure deps are fresh. To update deps without a full regeneration:
cd golem && wit-deps update
How It Fits Together
At build time, the sbt/mill GolemPlugin extracts the embedded agent_guest.wasm from plugin resources and writes it to the user project's .generated/agent_guest.wasm. Then golem-cli uses this base runtime to compose the final component: it injects the user's Scala.js bundle into the QuickJS runtime and wraps it as a proper Golem agent component.
The Scala SDK does not parse WIT to generate Scala bindings. Instead, Scala macros + ZIO Schema produce AgentMetadata at compile time, and WitTypeBuilder maps schema types to WIT-compatible JS representations at runtime. The WIT definitions only flow through the WASM guest runtime.
