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

# celesto sandbox list

> Use celesto sandbox list to view sandboxes, filter by state or preset, and produce JSON for scripts.

`celesto sandbox list` shows the sandboxes on your machine. Use it to find a sandbox name, check whether one is still running, or feed sandbox data into a script.

## Synopsis

```bash theme={null}
celesto sandbox list [OPTIONS]
```

## Examples

### List running sandboxes

```bash theme={null}
celesto sandbox list
```

### List every sandbox

```bash theme={null}
celesto sandbox list --all
```

### Filter by state

```bash theme={null}
celesto sandbox list --status stopped
```

### Filter by preset

A preset is a ready-made sandbox setup for an agent. Use `--preset` to show only sandboxes created by one preset. The table adds a Preset column so you can tell which agent produced each sandbox:

```bash theme={null}
celesto sandbox list --preset openclaw
# NAME              PRESET     STATUS   PID
# openclaw-work     openclaw   running  12345
```

Add `--all` to include that preset's sandboxes in every state:

```bash theme={null}
celesto sandbox list --preset openclaw --all
```

<Note>
  Preset filtering uses information saved when Celesto creates a sandbox. Sandboxes created by older Celesto releases and manually prepared sandboxes remain available through `celesto sandbox list --all`, but do not appear in preset-filtered results. Their Preset column shows `-`.
</Note>

For OpenClaw specifically, the shortcut `celesto openclaw list` shows only OpenClaw sandboxes and accepts the same `--all`, `--status`, and `--json` flags. See [Work with OpenClaw](/smolvm/features/coding-agents#work-with-openclaw) for the full workflow.

### Use JSON output

```bash theme={null}
celesto sandbox list --json
```

```json theme={null}
{
  "ok": true,
  "command": "sandbox.list",
  "exit_code": 0,
  "data": {
    "filters": {
      "all": false,
      "status": "running",
      "preset": null
    },
    "vms": [
      {
        "name": "openclaw-work",
        "preset": "openclaw",
        "status": "running",
        "pid": 12345,
        "ip_address": "172.16.0.2",
        "ssh_port": 2222,
        "warnings": []
      }
    ]
  },
  "error": null
}
```

## Options

<ParamField path="--all" type="flag">
  Show every sandbox, including stopped, created, paused, and errored sandboxes.
</ParamField>

<ParamField path="--status" type="string">
  Show only sandboxes in one state. Use one of the states printed by `celesto sandbox list --all`.
</ParamField>

<ParamField path="--preset" type="string">
  Show only sandboxes created by this preset, such as `openclaw` or `codex`. You can combine this with `--all` or `--status`.
</ParamField>

<ParamField path="--json" type="flag">
  Print a JSON envelope instead of a table. Each sandbox includes its stored `preset`, and `filters` includes the active `preset` filter.
</ParamField>

<Note>
  Use either `--all` or `--status`, not both.
</Note>

## Related commands

* [`celesto sandbox create`](/smolvm/cli/create) - Create a sandbox
* [`celesto sandbox info`](/smolvm/cli/overview) - Show details for one sandbox
* [`celesto sandbox delete`](/smolvm/cli/cleanup) - Delete one or more sandboxes


## Related topics

- [celesto sandbox snapshot](/smolvm/cli/snapshot.md)
- [celesto sandbox ssh](/smolvm/cli/ssh.md)
- [celesto sandbox prune](/smolvm/cli/sandbox-prune.md)
- [celesto sandbox create](/smolvm/cli/create.md)
- [celesto sandbox delete](/smolvm/cli/cleanup.md)