> ## Documentation Index
> Fetch the complete documentation index at: https://sandkiln.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# kiln sandbox

> Every kiln sandbox subcommand -- lifecycle, filesystem, preview, tunnel, snapshots.

## `kiln sandbox`

| Command | What it does |
| - | - |
| `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`](/api-reference/cli/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](/concepts/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. |

## Example

```bash theme={null}
kiln sandbox create --vcpu 2 --mem 1024
9f1ad482-e9ee-4a0f-9a7c-7826f77b9cfc

kiln sandbox write 9f1ad482-e9ee-4a0f-9a7c-7826f77b9cfc /tmp/config.json ./local-config.json

kiln sandbox exec 9f1ad482-e9ee-4a0f-9a7c-7826f77b9cfc -- cat /tmp/config.json
{"ok":true}

kiln sandbox snapshot 9f1ad482-e9ee-4a0f-9a7c-7826f77b9cfc
a1e9c3d2-2f0a-4b1e-9c3a-7d5e6f8b9c0d

kiln sandbox resume a1e9c3d2-2f0a-4b1e-9c3a-7d5e6f8b9c0d
f3b2a1c0-9e8d-4c7b-a6f5-e4d3c2b1a0f9
```

Every subcommand here takes the real opaque `<id>` a `create` printed, not a name — resolve a name back to a live id first with `by-name`, or skip straight to a live sandbox with `get-or-create`. See [Named sandboxes & persistent stop](/concepts/named-sandboxes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.