> ## 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.

# Sandboxes

> A running simulator instance with credentials, events, and branchable datasets.

A **sandbox** is one running simulator instance. Where a [Simulator](/guides/concepts/environments) is a definition ("a FHIR EHR", "a payer portal"), a sandbox is the live, provisioned version of it: a real FHIR store you can POST Bundles to, a real phone number you can call, a real portal URL you can log into. Sandboxes live inside [Playgrounds](/guides/concepts/playgrounds) (one per simulator in the environment) and are the source of truth the [verification engine](/guides/concepts/verification) reads after a rollout.

## Playground to Sandbox

```mermaid theme={null}
graph TD
  P["Playground"]:::engine --> S1["FHIR Sandbox<br/>(credentials: fhir_base_url, token_url, client_id/secret)"]:::state
  P --> S2["Voice Sandbox<br/>(credentials: phone_number)"]:::state
  P --> S3["Portal Sandbox<br/>(credentials: portal_url, username, password)"]:::state
  P --> S4["Fax Sandbox<br/>(credentials: inbound fax number)"]:::state
  P --> S5["SFTP Sandbox<br/>(credentials: sftp paths)"]:::state

  classDef engine fill:#2563eb,color:#fff,stroke:#1d4ed8
  classDef state fill:#fef3c7,color:#78350f,stroke:#f59e0b
```

A playground has one sandbox per simulator linked to its environment. Each sandbox carries its own set of credentials, own isolated dataset branch, and own event log.

## Credentials by Simulator Type

The shape of `credentials` on `GET /sandboxes/{id}` depends on the simulator type.

| Simulator              | Credentials shape                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| **FHIR**               | `fhir_base_url` (FHIR R4 endpoint), `token_url` (SMART on FHIR token endpoint), `client_id`, `client_secret`  |
| **Voice**              | `phone_number` (E.164 number to call)                                                                         |
| **HL7**                | `inbox_url` (GET inbound messages), `outbound_url` (POST outbound messages)                                   |
| **Payer / Web Portal** | `portal_url`, auto-generated `username` and `password`, `api_url` (REST base for the backing payer endpoints) |
| **Fax**                | Inbound fax number and upload endpoint                                                                        |
| **Files / SFTP**       | SFTP paths scoped to this sandbox under object storage                                                        |
| **X12**                | Transaction submission endpoint and response retrieval URL                                                    |
| **CDS Hooks**          | Hook registration URL                                                                                         |
| **Message**            | SMS/text endpoint URL                                                                                         |

All credentials are scoped to the specific sandbox. Nothing leaks across sandboxes or playgrounds.

## Events and Interactions

Every request to a sandbox gets recorded as an event. You can list them:

```bash theme={null}
curl "https://api.verial.ai/sandboxes/$SANDBOX_ID/events" \
  -H "Authorization: Bearer $VERIAL_API_KEY"
```

Events back the evidence shown in criterion runs. Common event types:

* **FHIR**: HTTP method, path, body, status code, response body.
* **HL7**: outbound `hl7_outbound` events with the full HL7v2 message.
* **Portal**: form submits, patient searches, auth submissions.
* **Voice**: recorded turns with speaker and transcript.
* **SFTP**: file upload and download events.

See [Interactions](/guides/concepts/interactions) for how these feed the verification engine.

## Dataset Branching and Checkpoints

When a [dataset](/guides/concepts/datasets) is linked to a sandbox, Verial creates a child dataset (`parentId` set) with copied config and copied GCS files. The sandbox operates on the child, so changes the agent makes (adding a Patient, uploading a file) stay isolated. A baseline **checkpoint** is written at branch time, storing a snapshot of the child's config.

```bash theme={null}
# Link a dataset (branches into a child + writes a baseline checkpoint)
curl -X POST "https://api.verial.ai/sandboxes/$SANDBOX_ID/datasets/ds_abc123" \
  -H "Authorization: Bearer $VERIAL_API_KEY"
```

## Standalone vs Playground Sandboxes

| Case               | How it arises                                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Playground sandbox | Created automatically when a [playground](/guides/concepts/playgrounds) is provisioned. `playground_id` is set.      |
| Standalone sandbox | Created directly via `POST /sandboxes` for interactive exploration or building dataset fixtures. No `playground_id`. |

Both shapes share the same event and dataset model.

## Teardown

Tear down a sandbox with `POST /sandboxes/{id}/teardown`, or let the owning playground tear it down when the benchmark run completes. Teardown releases the live resources (FHIR store, phone number, portal credentials) while preserving the event log and any branched datasets for later inspection.

## Creating a Sandbox

```bash theme={null}
# Standalone sandbox (no playground)
curl -X POST https://api.verial.ai/sandboxes \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"simulator_id": "sim_abc123"}'
# → save the returned id as $SANDBOX_ID

# Load a dataset
curl -X POST "https://api.verial.ai/sandboxes/$SANDBOX_ID/datasets/ds_abc123" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

# Inspect credentials and state
curl "https://api.verial.ai/sandboxes/$SANDBOX_ID" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

# Read the event log
curl "https://api.verial.ai/sandboxes/$SANDBOX_ID/events" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

# Release resources
curl -X POST "https://api.verial.ai/sandboxes/$SANDBOX_ID/teardown" \
  -H "Authorization: Bearer $VERIAL_API_KEY"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Interactions" icon="clipboard-list" href="/guides/concepts/interactions">
    The evidence captured on each sandbox during a rollout.
  </Card>

  <Card title="Sandboxes API" icon="code" href="/api-reference/resources/sandboxes">
    REST endpoints and full object reference.
  </Card>
</CardGroup>