Sandboxes

A sandbox is one running simulator instance. Where a Simulator 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 (one per simulator in the environment) and are the source of truth the verification engine reads after a rollout.

Playground to Sandbox

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:

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 for how these feed the verification engine.

Dataset Branching and Checkpoints

When a dataset 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.

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

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

Getting Started

Core Concepts

Simulators

Observability

Guides

Playground to Sandbox

Credentials by Simulator Type

Events and Interactions

Dataset Branching and Checkpoints

Standalone vs Playground Sandboxes

Teardown

Creating a Sandbox

Next Steps

Interactions

Sandboxes API

​Playground to Sandbox

​Credentials by Simulator Type

​Events and Interactions

​Dataset Branching and Checkpoints

​Standalone vs Playground Sandboxes

​Teardown

​Creating a Sandbox

​Next Steps

Interactions

Sandboxes API

Playground to Sandbox

Credentials by Simulator Type

Events and Interactions

Dataset Branching and Checkpoints

Standalone vs Playground Sandboxes

Teardown

Creating a Sandbox

Next Steps