iii-sandbox

The iii-sandbox worker boots ephemeral libkrun microVMs and runs code inside them, isolated from the host. Each sandbox boots in a few hundred milliseconds, runs commands or file operations scoped to the engine it lives on, and is reaped when idle; the overlay filesystem is discarded on stop. Its sandbox::* functions are called like any other iii function.

There are two ways in. sandbox::run is the fast path: it boots a VM, runs a code snippet, captures stdout/stderr, and tears the VM down in a single call. For multi-step work, several commands, multiple files, or inspecting a VM between steps, use the sandbox::create → sandbox::exec / sandbox::fs::* → sandbox::stop lifecycle and carry the returned sandbox id across calls.

Prerequisites: enable iii-sandbox under engine.workers (or the five-worker allowlist of a directly supervised engine), and provide hardware virtualization (Apple Silicon, or /dev/kvm on Linux). Intel Macs and Windows cannot boot sandboxes.

Get the contract from the engine

This page tells you WHEN and HOW to use the sandbox; the engine is the source of truth for every function's exact arguments and responses. Before you call any sandbox::* function, fetch its contract and build your payload from that, do not guess field names, types, or formats from memory:

engine::functions::info { function_id: "sandbox::<fn>" }

(e.g. { function_id: "sandbox::fs::write" }). The returned schema is authoritative; this skill never restates it.

Running an iii worker inside a sandbox

To author an iii worker (read the iii skill first), you write the worker code into the sandbox, install its deps, and run it as a process there, but the worker must still join the HOST engine bus to be useful.