create | Boot a new sandbox. --name <name>, --tag <key=value> (repeatable), --vcpu <count>, --mem <mib>, --image <id>, --rate-bandwidth <bytes-per-sec>, --rate-ops <ops-per-sec>, --drive <id[:ro]> (repeatable — attach an existing persistent drive, :ro for read-only). A plain create matching a configured pool’s image/resources (and no --drive/rate flags) resumes a warm snapshot automatically — see kiln pool. |
get-or-create | Resolve --name (required) to a sandbox in one call: live as-is, resumed if stopped, or created fresh. Prints the id and whether it was freshly created. --tag, --vcpu, --mem, --rate-bandwidth, --rate-ops, --drive (all used only if a fresh sandbox is created). |
by-name <name> | Resolve a name to a live sandbox’s id. |
ls | List sandboxes. --tag <key=value> (repeatable) filters. |
rm <id> | Stop a sandbox. Preserves state as a snapshot by default; --destroy fully destroys it instead — no snapshot, nothing left to resume. |
exec <id> <command> [args...] | Run a command inside a sandbox, wait for it to finish, print its output. Exits with the command’s own exit code. An arg starting with - needs a -- before it, or commander parses it as a kiln flag instead of passing it through. |
exec-stream <id> <command> [args...] | Start a command in the background and follow its output live (replay so far, then a live tail) until it exits. Ctrl+C detaches without stopping the command. |
logs <id> [session-id] | Without session-id: list this sandbox’s exec-stream sessions. With one: attach and follow it, exactly like right after exec-stream started it — works any number of times, including after the process has already finished. Neither survives resume()/fork()/a daemon restart. |
read <id> <path> | Read a file from a sandbox and print it to stdout. |
write <id> <path> <local-file> | Write a local file into a sandbox at the given path. |
chmod <id> <path> <mode> | Change a file’s permission bits (octal, e.g. 644). |
chown <id> <path> <uid> <gid> | Change a file’s owner/group. |
mkdir <id> <path> | Create a directory. |
rename <id> <from> <to> | Rename/move a file or directory. |
cp <id> <from> <to> | Copy a file within the sandbox. |
symlink <id> <target> <link-path> | Create a symlink. |
readlink <id> <path> | Print a symlink’s target. |
truncate <id> <path> <size> | Truncate (or extend) a file to an exact byte size. |
ls-dir <id> <path> | List a directory’s entries with real metadata (type, mode, size, mtime). |
pty <id> | Open a live, interactive shell session inside a sandbox over a WebSocket — distinct from exec’s request/response shape. Raw terminal mode: keystrokes, including Ctrl+C, pass straight through to the remote shell. Exit the remote shell (or Ctrl+D) to end the session. |
preview <id> <port> | Print the URL to reach a server listening on <port> inside a sandbox. --path <path> (default /). |
tunnel <id> <guest-port> | Expose a service running on this machine to code inside the sandbox — the reverse of preview. --local-port <port> (required), --local-host <host> (default 127.0.0.1). Runs in the foreground until Ctrl+C, which closes the tunnel cleanly. See Local tunnel. |
mount <id> <bucket> <endpoint> <mount-path> | Mount an S3-compatible bucket into a sandbox via rclone mount. --access-key <key>/--secret-key <key> (required), --read-only (mount read-only). Needs the optional FUSE-capable rootfs setup in SELF_HOSTING.md. Prints the new mount’s id. |
mounts <id> | List a sandbox’s active remote-storage mounts. |
unmount <id> <mount-id> | Unmount and tear down one remote-storage mount. |
snapshot <id> | Save a sandbox’s full state to disk and stop it. Prints the resulting snapshot id. |
snapshots | List snapshots. --source <sandbox-id> narrows to the one (if any) taken from that original sandbox id. |
resume <snapshot-id> | Boot a new sandbox from a snapshot, consuming it. Prints the new sandbox id. |
fork <snapshot-id> | Boot a new sandbox from a snapshot without consuming it. Prints the new sandbox id. |