iii-sandbox

Spawn ephemeral microVMs from worker code or the terminal. The daemon registers 14 sandbox::* triggers — 4 lifecycle ops plus 10 filesystem ops — every one called via iii.trigger(). Each sandbox boots in a few hundred milliseconds, runs commands isolated from the host, and is reaped when idle. The overlay filesystem is discarded on stop.

Implementation: crates/iii-worker/src/sandbox_daemon/. Ships inside the iii-worker binary; the engine starts the daemon as iii-worker sandbox-daemon when iii-sandbox appears in config.yaml.

Use it for: running untrusted code, AI-agent tool calls, one-shot scripts, per-request isolation.

Don't use it for: long-lived services (use a regular worker), durable stateful tasks (overlay is wiped on stop).

Host requirements

Sandboxes run as libkrun microVMs and need hardware virtualization on the host:

• macOS: Apple Silicon (M-series). Intel Macs can't boot sandboxes.
• Linux: /dev/kvm readable by the engine process.
• Windows: unsupported.

Hosts without hardware virtualization will fail sandbox::create with error S300 and a stderr tail from the failed VM process. See S300 in docs/api-reference/sandbox.mdx for the full diagnostic flow.

Sample Configuration

- name: iii-sandbox
  config:
    auto_install: true
    image_allowlist:
      - python
      - node
    default_idle_timeout_secs: 300
    max_concurrent_sandboxes: 32
    default_cpus: 1
    default_memory_mb: 512

iii worker add iii-sandbox appends this block to your config.yaml. Trim or extend image_allowlist and custom_images to control what callers can boot.

Configuration

Field	Type	Default	Description
auto_install	boolean	true	Pull the image from its OCI ref on first use when the rootfs isn't cached. Set false in air-gapped or pre-provisioned deployments — callers get S101 and operators pre-pull with iii worker add iiidev/.
image_allowlist	string[]	[]	Fail-closed list of image names that may be booted. Entries must be preset names (python, node) or keys from custom_images. Empty list denies everything — sandbox::create returns S100 for every request.
default_idle_timeout_secs	number	300	Reap a sandbox when now - last_exec_at exceeds this. The reaper runs every 10 s. Per-request idle_timeout_secs on sandbox::create overrides.
max_concurrent_sandboxes	number	32	Hard cap on live sandboxes. The 33rd concurrent sandbox::create returns S400. Size by host RAM (default RAM per sandbox × cap ≤ available RAM).
default_cpus	number	1	vCPUs per sandbox when the request omits cpus.
default_memory_mb	number	512	RAM ceiling per sandbox when the request omits memory_mb.
per_image_caps	map	{}	Per-image hard caps. Each value is { max_cpus: N, max_memory_mb: N }. Requests exceeding a cap return S400.
custom_images	map	{}	Deployment-specific images beyond the built-in presets. Map key is the name used in image_allowlist and the image field on sandbox::create; value is a fully-qualified OCI reference (e.g. ghcr.io/acme/my-app:1.2.3). Preset names (python, node) are reserved. See docs/api-reference/sandbox.mdx.

Triggers

All 14 triggers are dispatched via iii.trigger({ function_id, payload, timeoutMs }). Recommended timeoutMs is in each table; lifecycle ops have meaningful timeout pressure, filesystem ops generally don't (the daemon is local).

Lifecycle (4)

sandbox::create

Boot a microVM and return a sandbox_id. Recommended timeoutMs: 300_000 (cold pull can take 5-30 s).

Returns: { sandbox_id, image }.

sandbox::exec

Run a command inside a live sandbox. Recommended timeoutMs: 35_000 (daemon's 30 s default + 5 s margin).

Returns: { stdout, stderr, exit_code, timed_out, duration_ms, success }.

sandbox::list

Enumerate active sandboxes. Empty payload ({}). Returns an array of { sandbox_id, image, name, status, created_at, last_exec_at }.

sandbox::stop

Tear down a sandbox and reclaim resources.

Returns: { sandbox_id, stopped }.

Filesystem (10)

All filesystem triggers take sandbox_id (UUID) plus operation-specific fields. Bumping the sandbox's idle clock is automatic — fs activity counts as liveness. Errors return S2xx.

sandbox::fs::ls

Returns: { entries: FsEntry[] } where each entry has { name, is_dir, size, mode, mtime, is_symlink }.

sandbox::fs::stat

Returns: { name, is_dir, size, mode, mtime, is_symlink }.

sandbox::fs::mkdir

Returns: { created: boolean }.

sandbox::fs::write

Stream a file into the sandbox. The content field is a StreamChannelRef that the caller writes to (channel-paced — no envelope timeout cap).

Returns: { bytes_written, path }.

sandbox::fs::read

Stream a file out of the sandbox. Returns a StreamChannelRef the caller reads from.

Returns: { content: StreamChannelRef, size, mode, mtime }.

sandbox::fs::rm

Returns: { removed: boolean }.

sandbox::fs::chmod

Returns: { updated: number } — count of paths changed.

sandbox::fs::mv

Returns: { moved: boolean }.

sandbox::fs::grep

Recursive regex search.

Returns: { matches: FsMatch[], truncated } where each match has { path, line_no, byte_offset, line }.

sandbox::fs::sed

Find-and-replace across files. Pass either files (explicit list) or path (walk like grep) — exactly one. Passing both, or neither, returns S210.

Returns: { results: FsSedFileResult[], total_replacements }.

Example: create → exec → stop

import { registerWorker } from 'iii-sdk'

const iii = registerWorker('ws://127.0.0.1:49134')

const { sandbox_id } = await iii.trigger({
  function_id: 'sandbox::create',
  payload: { image: 'python', cpus: 1, memory_mb: 512 },
  timeoutMs: 300_000,
})

const out = await iii.trigger({
  function_id: 'sandbox::exec',
  payload: { sandbox_id, cmd: 'python3', args: ['-c', 'print(2 + 2)'] },
  timeoutMs: 35_000,
})
console.log(out.stdout) // "4\n"

await iii.trigger({
  function_id: 'sandbox::stop',
  payload: { sandbox_id, wait: true },
})

from iii import register_worker

iii = register_worker("ws://127.0.0.1:49134")

result = await iii.trigger({
    "function_id": "sandbox::create",
    "payload": {"image": "python", "cpus": 1, "memory_mb": 512},
    "timeout_ms": 300_000,
})
sandbox_id = result["sandbox_id"]

out = await iii.trigger({
    "function_id": "sandbox::exec",
    "payload": {"sandbox_id": sandbox_id, "cmd": "python3", "args": ["-c", "print(2 + 2)"]},
    "timeout_ms": 35_000,
})
print(out["stdout"])  # "4\n"

await iii.trigger({
    "function_id": "sandbox::stop",
    "payload": {"sandbox_id": sandbox_id, "wait": True},
})

CLI

The iii sandbox subcommands wrap a curated subset of the lifecycle and fs surface:

iii sandbox run <image> -- <cmd> [args...]    # one-shot create+exec+stop
iii sandbox create <image> [--idle-timeout N] # boot, print sandbox_id
iii sandbox exec <sandbox_id> -- <cmd> ...    # exec into a live sandbox
iii sandbox list
iii sandbox stop <sandbox_id>
iii sandbox upload <sandbox_id> <local> <remote>
iii sandbox download <sandbox_id> <remote> <local>

Anything outside this set (e.g. fs::grep, fs::sed, fs::chmod) is reachable only via iii.trigger() from worker code.

Errors

The daemon returns typed SandboxErrors with S-codes. Categories:

• S001–S004 — request shape errors (bad UUID, missing required field, invalid sandbox state).
• S100 — image not in image_allowlist. Add it to the allowlist or use custom_images.
• S101 — image not installed and auto_install: false. Pre-pull with iii worker add iiidev/.
• S102 — image registry/pull failure.
• S200–S219 — filesystem op errors (path not found, EISDIR, ENOTDIR, EPERM, …). The exact code identifies which operation failed.
• S300 — VM boot failed. Almost always missing virtualization (no /dev/kvm, Intel Mac, Windows host). Stderr tail attached.
• S400 — capacity exceeded (max_concurrent_sandboxes or per_image_caps).

For the full diagnostic flow per code (and how to surface stderr tails), see docs/api-reference/sandbox.mdx#s-codes.

See also

• docs/api-reference/sandbox.mdx — full payload reference, S-code diagnostics, custom images, environment variables, troubleshooting.
• docs/how-to/developing-sandbox-workers — how worker processes themselves run inside isolated microVMs (different topic from this trigger surface).