shell

The shell worker is the single door every agent uses to touch the OS: run a build, call a CLI, read a file, list a directory. Routing it all through shell::* and shell::fs::* keeps allowlists, denylists, timeouts, output caps, and a host-root jail in one enforceable place. Both surfaces take an optional target field that forwards the call into a live iii-sandbox microVM, so one allowlist policy gates host and sandbox execution alike.

Host-targeted shell::exec is not an isolation boundary. The denylist is a regex tripwire on argv.join(" "), and an allowlisted interpreter (sh, node, python3) can construct any forbidden token at runtime to bypass it. Run untrusted input with target: { kind: "sandbox", sandbox_id }. Prefer the shell::fs::* backends over exec-ing ls/stat/grep/rg: they stay in-process, respect the jail, and return structured results.

Sandbox forwarding (and shell::fs::* into a VM) requires the iii-sandbox worker; iii worker add shell does not pull it in. To surface shell::* to LLM agents, pair with the skills worker.