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 a denylist, timeouts, output caps, and an optional host-root jail (unjailed by default — see Boundaries) in one enforceable place. Both surfaces take an optional target field that forwards the call into a live iii-sandbox microVM, so the same denylist 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 any 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, honor fs.host_roots when it's configured, and return structured results.