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

# verial sandboxes

> Provision, inspect, and tear down sandboxes from the command line.

The `verial sandboxes` commands manage [Sandboxes](/api-reference/resources/sandboxes) — running instances of a single simulator, optionally attached to a dataset. A sandbox gives you live credentials (e.g. a FHIR base URL, payer `portal_url`, SFTP host) you can point an agent at for focused testing.

Authentication is required. See [verial auth](/cli/auth).

## Subcommands

| Command                           | Description                                    |
| --------------------------------- | ---------------------------------------------- |
| `verial sandboxes list`           | List sandboxes in your organization.           |
| `verial sandboxes create`         | Provision a sandbox from a simulator.          |
| `verial sandboxes get`            | Get a single sandbox by ID.                    |
| `verial sandboxes teardown`       | Tear down a sandbox and release its resources. |
| `verial sandboxes events`         | List a sandbox's event stream.                 |
| `verial sandboxes add-dataset`    | Attach a dataset to a sandbox.                 |
| `verial sandboxes remove-dataset` | Detach a dataset from a sandbox.               |

## verial sandboxes list

List sandboxes visible to your organization. Supports cursor pagination and filtering by playground.

Synopsis:

```bash theme={null}
verial sandboxes list [--playground-id <id>] [--cursor <cursor>] [--limit <n>]
```

Options:

| Flag                   | Description                                   | Default        |
| ---------------------- | --------------------------------------------- | -------------- |
| `--playground-id <id>` | Only return sandboxes in this playground.     | —              |
| `--cursor <cursor>`    | Pagination cursor returned from a prior page. | —              |
| `--limit <limit>`      | Items per page.                               | Server default |

REST equivalent: [GET /sandboxes](/api-reference/resources/sandboxes).

## verial sandboxes create

Provision a sandbox from a simulator. For portal/payer simulators the response includes a `portal_url` credential the agent can open directly.

Synopsis:

```bash theme={null}
verial sandboxes create --simulator-id <id> [--dataset-id <id>]
```

Options:

| Flag                  | Description                                  | Required |
| --------------------- | -------------------------------------------- | -------- |
| `--simulator-id <id>` | Simulator to provision.                      | Yes      |
| `--dataset-id <id>`   | Optional dataset to attach at creation time. | No       |

Example:

```bash theme={null}
verial sandboxes create \
  --simulator-id sim_clxyz789 \
  --dataset-id ds_clxyz001
```

REST equivalent: [POST /sandboxes](/api-reference/resources/sandboxes).

## verial sandboxes get

Fetch a single sandbox, including its credentials and attached datasets.

Synopsis:

```bash theme={null}
verial sandboxes get --id <id>
```

Example:

```bash theme={null}
verial sandboxes get --id sbx_clxyz123
```

REST equivalent: [GET /sandboxes/:id](/api-reference/resources/sandboxes).

## verial sandboxes teardown

Tear down a sandbox: release leased resources (phone numbers, FHIR store, portal session) and mark it inactive.

Synopsis:

```bash theme={null}
verial sandboxes teardown --id <id>
```

REST equivalent: [DELETE /sandboxes/:id](/api-reference/resources/sandboxes).

## verial sandboxes events

Stream the event log for a sandbox, most recent first. Events record every inbound/outbound interaction (FHIR request, fax send, portal submission, etc.).

Synopsis:

```bash theme={null}
verial sandboxes events --id <id> [--cursor <cursor>] [--limit <n>]
```

Example:

```bash theme={null}
verial sandboxes events --id sbx_clxyz123 --limit 50
```

REST equivalent: `GET /sandboxes/:id/events`.

## verial sandboxes add-dataset

Attach a dataset to an existing sandbox. A child dataset is branched so the sandbox's changes don't mutate the original.

Synopsis:

```bash theme={null}
verial sandboxes add-dataset --id <id> --dataset-id <datasetId>
```

REST equivalent: `POST /sandboxes/:id/datasets`.

## verial sandboxes remove-dataset

Detach a dataset from a sandbox.

Synopsis:

```bash theme={null}
verial sandboxes remove-dataset --id <id> --dataset-id <datasetId>
```

REST equivalent: `DELETE /sandboxes/:id/datasets/:datasetId`.

## Next Steps

<CardGroup cols={2}>
  <Card title="Sandboxes" icon="box" href="/api-reference/resources/sandboxes">
    Sandbox lifecycle, credentials, and events.
  </Card>

  <Card title="Simulators" icon="plug" href="/cli/simulators">
    Define the simulator a sandbox provisions.
  </Card>
</CardGroup>