iii-sandbox

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.

• Reaching the host engine: enable networking when you create the sandbox (the field is in the sandbox::create contract — fetch it), AND set the worker's engine-URL env (III_ENGINE_URL, e.g. ws://localhost:49134) IN THE sandbox::create env — NOT later at exec/run time. The localhost→host rewrite happens ONLY for the create-time env: a localhost / 127.0.0.1 engine URL set there is rewritten to the per-sandbox gateway so the worker reaches the host bus. The same localhost URL passed at sandbox::exec time is NOT rewritten — it points at the sandbox's own loopback, the worker silently fails to connect, and you will waste turns debugging TCP. So: put the engine URL in the create env; the worker process inherits it already rewritten.
• Run it backgrounded, never as a foreground exec: starting the worker with sandbox::exec "node index.mjs" blocks and times out (S200 exec timed out), because the process never returns. Launch it detached (… &, nohup, or sandbox::run shell mode) so the exec call returns while the worker keeps running — see the serialized-exec boundary below.
• Find the result: once the worker connects, its functions appear in engine::functions::list and any http trigger it binds is served by the Compose http worker; verify endpoints with web::fetch, not curl.
• EPHEMERAL by nature: a worker hosted in a sandbox dies when the sandbox is stopped or reaped (the overlay is discarded). That is fine for a demo, test, or one-off. Declare a long-lived worker as a Compose container instead of hosting it in a sandbox.

When to Use

• Execute untrusted or LLM-generated code without exposing the host.
• One-shot "code in, stdout out" — reach for sandbox::run.
• Spin up an ephemeral build worker, integration-test fixture, or throwaway iii worker.
• Read, write, search, or edit files inside an isolated filesystem.

Boundaries

• A sandbox is for running code and build steps, NOT for hosting a long-lived server. To expose an HTTP API or any always-on endpoint, author an iii worker and register a trigger for it (an http trigger is served by the Compose http worker) — do NOT start a server process (express, http.createServer, a framework listen()) inside the sandbox. A server you start here is not routed by iii, is unreachable as an iii endpoint, and as a foreground process hangs the exec slot until it times out. If the task is "build an iii worker," the deliverable is registered functions plus a trigger, not a running server.
• Not for long-lived services or durable state — the overlay is wiped on stop. Use a regular worker for daemons and the Compose state worker for persistence.