libkrun sandbox adapter - serves the iii sandbox router's sandbox::* calls as sandbox-libkrun::* in libkrun microVMs, and boots Compose's worker VMs.
iii trigger compose::add worker=sandbox-libkrunRun in your project with the iii engine running. Exact versions are immutable and digest-pinned.
Name and version of this sandbox adapter, and the sandbox contract version it implements.
The adapter's name, e.g. `"sandbox-libkrun"`.
The contract version the adapter implements.
List bootable images: bundled presets plus operator-registered custom_images. Call this before sandbox::create when you don't know what's available.
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.
Create an ephemeral sandbox VM. `image` must be a preset (`"python"`, `"node"`) or a key from the adapter's `custom_images` config; OCI refs are NOT accepted unless they match a catalog key. `env` accepts both `Vec<"K=V">` and `{ K: V }` map shapes.
vCPU count, at least 1; daemon/image default applies when omitted.
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.
Auto-stop the VM after this many seconds of inactivity; daemon default applies when omitted.
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 the adapter's `custom_images` config — 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 cap in MiB, at least 64; daemon/image default applies when omitted.
Human label surfaced by `sandbox::list`; not an identifier.
Whether the VM gets outbound networking; daemon default when omitted.
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.
Argv tail passed to `cmd` (each entry is one argv slot).
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.
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.
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.
UUID returned by `sandbox::create`.
Base64-encoded bytes piped to the child's stdin.
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.
Working directory inside the sandbox; `/` when omitted.
`stderr` was cut at the 1 MiB output cap. Since contract 1.1.
`stdout` was cut at the 1 MiB output cap. Since contract 1.1.
Change file permissions (and optionally owner) inside a sandbox. Example: { sandbox_id: "...", path: "/home/app/script.sh", mode: "0755" }
Optional GID to chown to. Pair with `uid` for a full chown.
Octal permissions (e.g. `"0644"`, `"0755"`).
Absolute path to modify inside the sandbox guest.
Apply recursively to all entries under `path`.
UUID returned by `sandbox::create`.
Optional UID to chown to. Pair with `gid` for a full chown.
Search for a regex pattern in files inside a sandbox. Walks `path` recursively by default. Example: { sandbox_id: "...", path: "/home/app/src", pattern: "TODO" }
Gitignore-style exclude filter applied relative to `path`.
Case-insensitive match.
Gitignore-style include filter applied relative to `path`.
Maximum bytes per matched line before content is truncated with `…`. Default 4096.
Maximum number of matches before truncation. Default 10_000.
Root path to search inside the sandbox guest. Treated as a directory when `recursive: true`, else as a single file.
Regex pattern (Rust regex syntax, anchored fragments allowed).
Descend into subdirectories under `path`. Defaults to true.
UUID returned by `sandbox::create`.
List directory contents inside a sandbox. Example: { sandbox_id: "...", path: "/home/app" }
Absolute path of the directory to list inside the sandbox guest.
UUID returned by `sandbox::create`.
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 }
Octal permissions for the new directory (e.g. `"0755"`).
Create intermediate parent directories like `mkdir -p`.
Absolute path of the directory to create inside the sandbox guest.
UUID returned by `sandbox::create`.
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" }
Destination absolute path inside the sandbox guest.
Allow overwriting `dst` if it already exists.
UUID returned by `sandbox::create`.
Source absolute path inside the sandbox guest.
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" }
Absolute path to read inside the sandbox guest.
UUID returned by `sandbox::create`.
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.
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`.
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 }
Absolute path to remove inside the sandbox guest.
Remove directories and their contents recursively (like `rm -rf`).
UUID returned by `sandbox::create`.
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" }
Gitignore-style exclude filter applied to paths relative to `path`. Only meaningful with `path`.
Legacy form: explicit list of paths to rewrite.
Gitignore-style include filter applied to paths relative to `path`. Only meaningful with `path`.
New form: walk `path` like grep does. May be a directory or a single file. Mutually exclusive with `files`.
Whether to descend into subdirectories. Only meaningful with `path`. Defaults to `true` so the path-form behaves like grep.
UUID returned by `sandbox::create`.
Stat a path inside a sandbox. Example: { sandbox_id: "...", path: "/home/app/index.js" }
Absolute path to inspect inside the sandbox guest.
UUID returned by `sandbox::create`.
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" }
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.
Base64-encoded inline body for small binary payloads. Mutually exclusive with `content`.
Octal permissions for the new file (default `"0644"`).
Create missing parent directories before writing.
Absolute destination path inside the sandbox guest.
UUID returned by `sandbox::create`.
List active sandboxes
Execs running right now.
Any exec running. NOTE: this no longer implies the next exec will be refused — a sandbox admits `max_concurrent_exec_per_sandbox` at once. Use `exec_in_flight` / `exec_slots_free` for admission decisions; a caller that polls this waiting for `false` will wait forever against a resident process while slots sit idle.
Execs this sandbox would admit before returning S003.
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" }
The actual code to run. Written to a `/tmp/run.{ext}` file inside the sandbox; the chosen interpreter runs that file.
Env vars exposed to the interpreter. Accepts both `Vec<"K=V">` and `{ K: V }` map shapes (same as `sandbox::exec.env`).
Optional sibling files (extra source modules, config, fixtures).
UTF-8 file body. Streaming and base64 are not supported here; callers needing those should use `sandbox::create` + repeated `sandbox::fs::write` calls instead.
Absolute path inside the sandbox guest where the file lands.
Catalog name of the image to boot (preset or `custom_images` key). Same value space as `sandbox::create`.
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).
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.
Base64-encoded bytes piped to the interpreter's stdin.
Kill-after window for the interpreter, in ms. Defaults to 300_000 (5 minutes); pass a smaller value to fail fast on quick probes.
Present only if `keep_sandbox: true` was set on the request. Otherwise null (sandbox auto-stopped).
As `ExecResponse::stderr_truncated`.
As `ExecResponse::stdout_truncated`.
Stop and remove a running sandbox. Set `wait: true` to block until the VM process exits and resources are reclaimed.
Block until the VM is fully reaped before returning.
Remove the state of `state_key`'s worker VM. Needs the project token; S502 while that VM is preparing or running.
Stream a worker VM's console log into `channel`, one `LogRecord` JSON per text frame, from `cursor` on; with `follow`, until the instance exits. Needs the project token.
Writer end of a channel Compose created; one `LogRecord` JSON per text frame.
`LogRecord.cursor` of the last record the caller has; reading resumes right after it. Opaque to Compose: an offset into all the instance logged, valid across a log rotation. A cursor past the end (another instance's) reads from the oldest record kept.
Keep the channel open while the instance runs.
Validate a worker VM's source and pull its base image; idempotent. Needs the project token in `auth`, and `host_path` under the host roots.
Per-project token.
Where the worker's code comes from.
The bundle in Compose's package cache.
Manifest name, not the container key.
Boot the worker VM of `state_key` as its next instance. Needs the project token; S502 while that VM is preparing or running.
Per-project token.
The engine's URL as seen from the host.
Complete guest env. Never on the `__vm-boot` argv: the adapter writes it to `__vm-boot`'s stdin, which sends it to the guest init over the `iii.env` virtio-console port, not the kernel cmdline (only a build without an embedded init still uses the cmdline).
Where the worker's code comes from.
The bundle in Compose's package cache.
Manifest name, not the container key.
Hash of the compose state dir and container key; the same key gets the same persistent upper.
Container key; becomes `III_WORKER_NAME`.
Increments on every boot of this `vm_id`.
Opaque; stable per `state_key`.
State of one worker VM instance. Needs the project token.
The signal that ended the VM, if one did.
SIGTERM a worker VM instance, then SIGKILL after `grace_ms` (0 kills at once); returns its final status. Needs the project token.
Names the boot to stop, so a stale stop cannot hit a newer one.
The signal that ended the VM, if one did.
Find workers, kits and executables, or jump to a page.