Skip to content
Registry

iii-sandbox

v0.16.0-next.3

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

Engine module
Baked into the iii engine; no separate install required.

Install

bash
iii trigger compose::add worker=iii-sandbox@0.16.0-next.3

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions14

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

Triggers0

No triggers registered

Search the registry

Find workers, kits and executables, or jump to a page.