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: the worker is enabled by adding iii-sandbox to config.yaml, and the host needs 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