shell

Unix shell and filesystem worker on the iii bus. Every agent that needs to touch the OS (run a build, read a file, list a directory, call a CLI) goes through shell::* and shell::fs::*, so allowlists, timeouts, output caps, and a host-root jail live in one place. Both surfaces accept an optional target field that forwards the call into a live iii-sandbox microVM, so the same allowlist policy gates host and sandbox execution.

Host-targeted shell::exec is not an isolation boundary. The denylist is a regex tripwire on argv.join(" "). A caller running an allowlisted interpreter (sh, node, python3) can construct any forbidden token at runtime and bypass it. For untrusted input, pass target: { kind: "sandbox", sandbox_id } so the call forwards into a microVM. Prefer shell::fs::ls, shell::fs::stat, and shell::fs::grep over exec-ing the same tools; the fs backends stay in-process, respect the jail, and return structured results.

For sandbox-targeted execution and shell::fs::* forwarding, install iii-sandbox; iii worker add shell does not currently pull it in. For surfacing shell::* to LLM agents, pair with skills:

iii worker add iii-sandbox
iii worker add skills

Additional Resources

• Changing a path's permissions
• Running a one-shot command in the foreground
• Spawning a long-running command as a background job
• Searching a directory tree with regex
• Terminating a running background job
• Surveying current background jobs
• Listing a directory inside the jail
• Creating a directory inside the jail
• Renaming or moving a path inside the jail
• Streaming a file's bytes through a channel
• Removing a path inside the jail
• Find-and-replace across files
• Reading a single path's metadata
• Polling a background job to completion
• Streaming bytes into a file