iii / worker
$worker

shell

v0.3.5

Unix shell + filesystem worker — exec with allowlist/denylist/timeout/output caps and background jobs; fs::ls|stat|mkdir|rm|chmod|mv|grep|sed|read|write with host jail, denylist, size caps, and sandbox-target forwarding

  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64

skill doc

skills/exec_bg.md

Spawning a long-running command as a background job

When to use

  • Builds, long greps, watchers; anything that does not fit inside max_timeout_ms.
  • Keeping the calling turn responsive while the command runs.
  • "Run cargo build and report when it is done": pair with shell::status polling.

Notes

  • Same payload shape as shell::exec. The same per-field deserialisers catch wrong-type fields up front.
  • Allowlist and denylist gate the spawn the same way; a blocked argv comes back as the trigger Err and the job is never inserted into the table.
  • Host-targeted background jobs ignore timeout_ms (preserves the unbounded host-bg semantic). Only shell::kill or natural exit ends them.
  • Sandbox-targeted background jobs honour timeout_ms; the value is clamped through cfg.resolve_timeout and forwarded to sandbox::exec.
  • Concurrency cap is cfg.max_concurrent_jobs (default 16). Past the cap, the call returns Err and the spawned child is killed before the trigger response.
  • Sandbox-backed jobs cannot be hard-killed: shell::kill flips the record to killed immediately, but the in-VM process keeps running until its timeout_ms expires (or sandbox::stop tears the VM down).