skip to content
iii / worker
$worker

iii-sandbox

v0.13.0

Spawn ephemeral microVMs and expose 14 sandbox::* triggers (lifecycle + filesystem) for isolated command execution and file ops.

iiiverified
8,779 installs133 in 7d0 today
install
$iii worker add iii-sandbox@0.13.0
engine
14functions0triggers0skills0depsv0.13.0version
repoiii-hq/iii

exact versions are immutable; binary and bundle artifacts are digest-pinned.

engine module
baked into the iii engine; no separate install required.

functions

14

sandbox::create

function

Create an ephemeral sandbox VM from a preset image

request
  • cpusinteger· uint32min 0

    vCPU count; daemon/image default applies when omitted.

  • envstring[]

    `"K=V"` entries injected into the VM's environment.

  • idle_timeout_secsinteger· uint64min 0

    Auto-stop the VM after this many seconds of inactivity; daemon default applies when omitted.

  • imagestringrequired

    Catalog name of the image to boot. Bundled presets are `"python"` and `"node"`; pass either string verbatim. The only other accepted values are the literal keys of `sandbox.custom_images` in `iii.config.yaml` — set by the operator. Do NOT pass an OCI ref like `"ghcr.io/iii-hq/node:latest"` or `"docker.io/library/node:20"` unless that exact string is the catalog key. Unknown values return S100 with the allowed set in the error message.

  • memory_mbinteger· uint32min 0

    Memory cap in MiB; daemon/image default applies when omitted.

  • namestring

    Human label surfaced by `sandbox::list`; not an identifier.

  • networkboolean

    Whether the VM gets outbound networking; daemon default when omitted.

response
  • imagestringrequired
  • sandbox_idstringrequired

sandbox::exec

function

Execute a command inside a live sandbox

request
  • argsstring[]

    Argv tail passed to `cmd` (each entry is one argv slot).

  • cmdstringrequired

    The binary to execute as a single string — NOT a shell line. `"node"` is correct; `"node -v"` is not (put `-v` in `args`). `handle_exec` rejects values containing whitespace with S001. Shell metacharacters (`;`, `|`, `&&`, `>`, etc.) in `cmd` are not interpreted — the runner spawns `cmd` literally. Use a wrapper script inside the VM if you need shell behavior.

  • envstring[]

    `"K=V"` entries (NOT a map) added to the child's environment.

  • sandbox_idstringrequired

    UUID returned by `sandbox::create`.

  • stdinstring

    Base64-encoded bytes piped to the child's stdin.

  • timeout_msinteger· uint64min 0

    Kill-after window in ms; daemon default applies when omitted.

  • workdirstring

    Working directory inside the sandbox; image default when omitted.

response
  • duration_msinteger· uint64requiredmin 0
  • exit_codeinteger· int32
  • stderrstringrequired
  • stdoutstringrequired
  • successbooleanrequired
  • timed_outbooleanrequired

sandbox::fs::chmod

function

Change file permissions inside a sandbox

request
valueunknown
response
valueunknown

sandbox::fs::grep

function

Search for a pattern in files inside a sandbox

request
valueunknown
response
valueunknown

sandbox::fs::ls

function

List directory contents inside a sandbox

request
valueunknown
response
valueunknown

sandbox::fs::mkdir

function

Create a directory inside a sandbox

request
valueunknown
response
valueunknown

sandbox::fs::mv

function

Move or rename a path inside a sandbox

request
valueunknown
response
valueunknown

sandbox::fs::read

function

Stream-download a file from a sandbox

request
valueunknown
response
valueunknown

sandbox::fs::rm

function

Remove a file or directory inside a sandbox

request
valueunknown
response
valueunknown

sandbox::fs::sed

function

Search-and-replace in files inside a sandbox

request
valueunknown
response
valueunknown

sandbox::fs::stat

function

Stat a path inside a sandbox

request
valueunknown
response
valueunknown

sandbox::fs::write

function

Stream-upload a file into a sandbox

request
valueunknown
response
valueunknown

sandbox::list

function

List active sandboxes

request
empty object
response
  • sandboxesobject[]required
    • age_secsinteger· uint64requiredmin 0
    • exec_in_progressbooleanrequired
    • imagestringrequired
    • namestring
    • sandbox_idstringrequired
    • stoppedbooleanrequired

sandbox::stop

function

Stop and remove a running sandbox

request
  • sandbox_idstringrequired
  • waitboolean

    Block until the VM is fully reaped before returning.

response
  • sandbox_idstringrequired
  • stoppedbooleanrequired

triggers

0
no triggers registered