iii / worker
$worker

iii-sandbox

v0.19.1-next.1

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.

functions

16

sandbox::catalog::list

function

List bootable images: bundled presets plus operator-registered custom_images. Call this before sandbox::create when you don't know what's available.

request
empty object
response
  • imagesobject[]required

    Every image the daemon will accept on `sandbox::create.image`. Presets come first in stable order; custom entries follow, sorted by `name` for determinism so an agent that diffs two `catalog::list` responses sees stable output.

    • kindone ofrequired
      one of (2)
      variant 1
      valuestringenum: preset
      variant 2
      valuestringenum: custom
    • namestringrequired
    • oci_refstringrequired

sandbox::create

function

Create an ephemeral sandbox VM. `image` must be a preset (`"python"`, `"node"`) or a `custom_images` key from iii.config.yaml; OCI refs are NOT accepted unless they match a catalog key. `env` accepts both `Vec<"K=V">` and `{ K: V }` map shapes.

request
  • cpusinteger· uint32min 0

    vCPU count; daemon/image default applies when omitted.

  • envall of

    Environment entries injected into the VM. Accepts either a `Vec<"K=V">` (original wire shape) or a `{ K: V }` map. `handle_create` normalises to the `Vec<String>` shape the boot path expects before invoking the launcher.

    all of (1)
    variant 1
    any of (2)
    variant 1
    itemsstring[]
    variant 2
    empty object
  • 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. `cmd` accepts three shapes: (1) a shell-style line that gets shlex-split (`cmd: "node -v"`), (2) `cmd` + `args` (the POSIX shape, `cmd: "node", args: ["-v"]`), (3) an `argv` array (`argv: ["node", "-v"]`). Shell metacharacters in the shell-line shape are NOT interpreted; use `sandbox::run` with `lang: "shell"` for bash semantics. `env` accepts both `Vec<"K=V">` and `{ K: V }` map shapes.

request
  • argsstring[]

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

  • argvstring[]

    Alternative input shape: a single argv array where the first element is the binary and the rest are arguments. Mutually exclusive with `cmd` having whitespace OR `args` being set.

  • cmdstring

    The binary to execute. Accepts three shapes (`handle_exec` picks one and normalises `cmd`/`args` before passing to the runner): 1. **Shell line**: `cmd: "node /home/app/index.js"`. If `cmd` contains whitespace AND `args` is empty AND `argv` is empty, `cmd` is shlex-split into `(head, tail)` and `head` becomes the binary while `tail` becomes the argv. 2. **cmd + args**: `cmd: "node", args: ["-v"]`. The classic POSIX shape; unchanged from earlier versions. 3. **argv array**: `argv: ["node", "/home/app/index.js"]`. Wins over `cmd`/`args` if non-empty; the first element is the binary, the rest are arguments. Shlex is NOT bash. Shell metacharacters (`;`, `|`, `&&`, `>`, pipes, redirects, variable expansion) inside the shell-line shape are split as text, not interpreted. Use `sandbox::run` with `lang: "shell"` if you need bash semantics.

  • envall of

    Environment entries added to the child. Accepts either a `Vec<"K=V">` (the original wire shape) or a `{ K: V }` map. `handle_exec` normalises to `Vec<String>` before invoking the runner.

    all of (1)
    variant 1
    any of (2)
    variant 1
    itemsstring[]
    variant 2
    empty object
  • 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. Defaults to 300_000 (5 minutes) — sized for cold `npm install` / `pip install` / `cargo build`. Pass a smaller value (e.g. 10_000) for probes and version checks.

  • 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 (and optionally owner) inside a sandbox. Example: { sandbox_id: "...", path: "/home/app/script.sh", mode: "0755" }

request
  • gidinteger· uint32min 0

    Optional GID to chown to. Pair with `uid` for a full chown.

  • modestringrequired

    Octal permissions (e.g. `"0644"`, `"0755"`).

  • pathstringrequired

    Absolute path to modify inside the sandbox guest.

  • recursiveboolean

    Apply recursively to all entries under `path`.

  • sandbox_idstringrequired

    UUID returned by `sandbox::create`.

  • uidinteger· uint32min 0

    Optional UID to chown to. Pair with `gid` for a full chown.

response
  • updatedinteger· uint64requiredmin 0

sandbox::fs::grep

function

Search for a regex pattern in files inside a sandbox. Walks `path` recursively by default. Example: { sandbox_id: "...", path: "/home/app/src", pattern: "TODO" }

request
  • exclude_globstring[]

    Gitignore-style exclude filter applied relative to `path`.

  • ignore_caseboolean

    Case-insensitive match.

  • include_globstring[]

    Gitignore-style include filter applied relative to `path`.

  • max_line_bytesinteger· uint64min 0

    Maximum bytes per matched line before content is truncated with `…`. Default 4096.

  • max_matchesinteger· uint64min 0

    Maximum number of matches before truncation. Default 10_000.

  • pathstringrequired

    Root path to search inside the sandbox guest. Treated as a directory when `recursive: true`, else as a single file.

  • patternstringrequired

    Regex pattern (Rust regex syntax, anchored fragments allowed).

  • recursiveboolean

    Descend into subdirectories under `path`. Defaults to true.

  • sandbox_idstringrequired

    UUID returned by `sandbox::create`.

response
  • matchesobject[]required
    • contentstringrequired
    • lineinteger· uint64requiredmin 0
    • pathstringrequired
  • truncatedbooleanrequired

sandbox::fs::ls

function

List directory contents inside a sandbox. Example: { sandbox_id: "...", path: "/home/app" }

request
  • pathstringrequired

    Absolute path of the directory to list inside the sandbox guest.

  • sandbox_idstringrequired

    UUID returned by `sandbox::create`.

response
  • entriesobject[]required
    • is_dirbooleanrequired
    • is_symlinkbooleanrequired
    • modestringrequired
    • mtimeinteger· int64required
    • namestringrequired
    • sizeinteger· uint64requiredmin 0

sandbox::fs::mkdir

function

Create a directory inside a sandbox. Pass `parents:true` to make missing parents like `mkdir -p`. Example: { sandbox_id: "...", path: "/home/app/cache", mode: "0755", parents: true }

request
  • modestring

    Octal permissions for the new directory (e.g. `"0755"`).

  • parentsboolean

    Create intermediate parent directories like `mkdir -p`.

  • pathstringrequired

    Absolute path of the directory to create inside the sandbox guest.

  • sandbox_idstringrequired

    UUID returned by `sandbox::create`.

response
  • createdbooleanrequired

sandbox::fs::mv

function

Move or rename a path inside a sandbox. Pass `overwrite:true` to clobber an existing destination. Example: { sandbox_id: "...", src: "/home/app/old.js", dst: "/home/app/new.js" }

request
  • dststringrequired

    Destination absolute path inside the sandbox guest.

  • overwriteboolean

    Allow overwriting `dst` if it already exists.

  • sandbox_idstringrequired

    UUID returned by `sandbox::create`.

  • srcstringrequired

    Source absolute path inside the sandbox guest.

response
  • movedbooleanrequired

sandbox::fs::read

function

Read a file from a sandbox. Always returns `content`: a StreamChannelRef callers can subscribe to for the full file bytes. For UTF-8 text files under 1 MiB, the response also carries an inline `body` string so callers can short-circuit the subscription. Example: { sandbox_id: "...", path: "/home/app/index.js" }

request
  • pathstringrequired

    Absolute path to read inside the sandbox guest.

  • sandbox_idstringrequired

    UUID returned by `sandbox::create`.

response
  • bodystring

    Inline UTF-8 body. Populated for text files under [`INLINE_BUFFER_CAP`] (1 MiB) that decode cleanly as UTF-8. `None` for large or binary files; subscribe to `content` instead. When `Some`, the same bytes are also delivered through `content` so legacy callers keep working — new callers can use `body` directly and skip the channel subscription.

  • contentall ofrequired

    Channel ref for the file body. Always set; callers can subscribe to receive the full file contents as bytes. Preserved for wire compatibility with peers that statically type this field as `StreamChannelRef`.

    all of (1)
    variant 1
    • access_keystringrequired
    • channel_idstringrequired
    • directionstringrequiredenum: read, write
  • modestringrequired
  • mtimeinteger· int64required
  • sizeinteger· uint64requiredmin 0

sandbox::fs::rm

function

Remove a file or directory inside a sandbox. Pass `recursive:true` to remove directories with contents. Example: { sandbox_id: "...", path: "/home/app/temp", recursive: true }

request
  • pathstringrequired

    Absolute path to remove inside the sandbox guest.

  • recursiveboolean

    Remove directories and their contents recursively (like `rm -rf`).

  • sandbox_idstringrequired

    UUID returned by `sandbox::create`.

response
  • removedbooleanrequired

sandbox::fs::sed

function

Find-and-replace in files inside a sandbox. Pass either `path` (walked like grep) OR `files` (explicit list), not both. Example: { sandbox_id: "...", path: "/home/app/src", pattern: "foo", replacement: "bar" }

request
  • exclude_globstring[]

    Gitignore-style exclude filter applied to paths relative to `path`. Only meaningful with `path`.

  • filesstring[]

    Legacy form: explicit list of paths to rewrite.

  • first_onlyboolean
  • ignore_caseboolean
  • include_globstring[]

    Gitignore-style include filter applied to paths relative to `path`. Only meaningful with `path`.

  • pathstring

    New form: walk `path` like grep does. May be a directory or a single file. Mutually exclusive with `files`.

  • patternstringrequired
  • recursiveboolean

    Whether to descend into subdirectories. Only meaningful with `path`. Defaults to `true` so the path-form behaves like grep.

  • regexboolean
  • replacementstringrequired
  • sandbox_idstringrequired

    UUID returned by `sandbox::create`.

response
  • resultsobject[]required
    • errorstring
    • pathstringrequired
    • replacementsinteger· uint64requiredmin 0
    • successbooleanrequired
  • total_replacementsinteger· uint64requiredmin 0

sandbox::fs::stat

function

Stat a path inside a sandbox. Example: { sandbox_id: "...", path: "/home/app/index.js" }

request
  • pathstringrequired

    Absolute path to inspect inside the sandbox guest.

  • sandbox_idstringrequired

    UUID returned by `sandbox::create`.

response
  • is_dirbooleanrequired
  • is_symlinkbooleanrequired
  • modestringrequired
  • mtimeinteger· int64required
  • namestringrequired
  • sizeinteger· uint64requiredmin 0

sandbox::fs::write

function

Write a file into a sandbox. `content` accepts a UTF-8 string (recommended for source/text), a StreamChannelRef object (for large uploads), or use `content_b64` for small binary. Example: { sandbox_id: "...", path: "/home/app/index.js", content: "console.log('hi')\n" }

request
  • contentany of

    File body. Pass a UTF-8 string for source/text (the agent-natural form), or a `StreamChannelRef` object for streaming large/binary uploads. Mutually exclusive with `content_b64`; exactly one of the two must be set.

    any of (2)
    variant 1
    any of (2)
    variant 1
    valuestring
    variant 2
    all of (1)
    variant 1
    • access_keystringrequired
    • channel_idstringrequired
    • directionstringrequiredenum: read, write
    variant 2
    valuenull
  • content_b64string

    Base64-encoded inline body for small binary payloads. Mutually exclusive with `content`.

  • modestring

    Octal permissions for the new file (default `"0644"`).

  • parentsboolean

    Create missing parent directories before writing.

  • pathstringrequired

    Absolute destination path inside the sandbox guest.

  • sandbox_idstringrequired

    UUID returned by `sandbox::create`.

response
  • bytes_writteninteger· uint64requiredmin 0
  • pathstringrequired

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::run

function

Run code in an ephemeral sandbox in ONE call. Composes create + fs::write + exec + stop. `lang` selects the interpreter (`node`, `python`, `shell`, or a custom binary path). Sandbox auto-stops on success and on failure unless `keep_sandbox: true`. Example: { image: "node", code: "console.log('hi')", lang: "node" }

request
  • codestringrequired

    The actual code to run. Written to a `/tmp/run.{ext}` file inside the sandbox; the chosen interpreter runs that file.

  • envall of

    Env vars exposed to the interpreter. Accepts both `Vec<"K=V">` and `{ K: V }` map shapes (same as `sandbox::exec.env`).

    all of (1)
    variant 1
    any of (2)
    variant 1
    itemsstring[]
    variant 2
    empty object
  • filesobject[]

    Optional sibling files (extra source modules, config, fixtures).

    • contentstringrequired

      UTF-8 file body. Streaming and base64 are not supported here; callers needing those should use `sandbox::create` + repeated `sandbox::fs::write` calls instead.

    • pathstringrequired

      Absolute path inside the sandbox guest where the file lands.

  • imagestringrequired

    Catalog name of the image to boot (preset or `custom_images` key). Same value space as `sandbox::create`.

  • keep_sandboxboolean

    If true, the sandbox is NOT stopped after the run completes; `sandbox_id` is returned so the caller can poke around. Default false (the sandbox is torn down on either success or failure).

  • langstringrequired

    Selects the interpreter and file extension. Required. Built-in values: `"node"`, `"python"`, `"shell"`. Any other string is treated as a literal interpreter binary path inside the VM and the file is written to `/tmp/run.txt`. There is no default — there's no honest universal answer to "what language is this code", and silently defaulting to shell makes Python or JS code produce confusing line-by-line failures.

  • stdinstring

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

  • timeout_msinteger· uint64min 0

    Kill-after window for the interpreter, in ms. Defaults to 300_000 (5 minutes); pass a smaller value to fail fast on quick probes.

response
  • duration_msinteger· uint64requiredmin 0
  • exit_codeinteger· int32
  • sandbox_idstring

    Present only if `keep_sandbox: true` was set on the request. Otherwise null (sandbox auto-stopped).

  • stderrstringrequired
  • stdoutstringrequired
  • successbooleanrequired
  • timed_outbooleanrequired

sandbox::stop

function

Stop and remove a running sandbox. Set `wait: true` to block until the VM process exits and resources are reclaimed.

request
  • sandbox_idstringrequired
  • waitboolean

    Block until the VM is fully reaped before returning.

response
  • sandbox_idstringrequired
  • stoppedbooleanrequired

triggers

0
no triggers registered