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

# Playgrounds

> A provisioned, running environment ready for agent rollouts.

A **playground** is a running instance of an [Environment](/guides/concepts/environments). When a playground is provisioned, every simulator in the environment comes up as a live [Sandbox](/guides/concepts/sandboxes), datasets are loaded, and credentials are returned. Task rollouts execute inside a playground, and the [verification engine](/guides/concepts/verification) reads the playground's final sandbox state to score [criteria](/guides/concepts/criteria).

## Lifecycle

```mermaid theme={null}
graph LR
  C["Created"]:::input --> P["Provisioning"]:::engine
  P --> A["Active"]:::state
  A --> T["Teardown"]:::output

  classDef input fill:#e0f2fe,color:#1e3a5f,stroke:#3b82f6
  classDef state fill:#fef3c7,color:#78350f,stroke:#f59e0b
  classDef engine fill:#2563eb,color:#fff,stroke:#1d4ed8
  classDef output fill:#f0fdf4,color:#166534,stroke:#22c55e
```

1. **Created.** A playground row is written referencing the source environment.
2. **Provisioning.** For each simulator in the environment, Verial spins up a sandbox, allocates resources (FHIR stores under the GCP Healthcare API, leased phone numbers, portal URLs, fax numbers, SFTP paths), and branches any linked datasets into the sandbox.
3. **Active.** All sandboxes are up and their credentials are available. Your agent can now drive rollouts against the sandbox endpoints.
4. **Teardown.** Resources are released (FHIR stores deleted, phone numbers released back to the pool, portal users removed). Interaction logs and sandbox events are retained so you can inspect evidence after the fact.

## What Provisioning Does

Provisioning is where the environment's definition becomes running infrastructure:

* **FHIR sandboxes** get a dedicated GCP Healthcare API FHIR store (named with a `fhir-` prefix), a SMART on FHIR token endpoint, and an OAuth2 client.
* **Voice sandboxes** lease a phone number from the pool.
* **Portal sandboxes** get a unique portal URL with auto-generated username and password.
* **Fax sandboxes** lease an inbound fax number.
* **SFTP / Files sandboxes** get a scoped storage prefix.
* **Datasets** linked to each simulator are branched to a child dataset and loaded into that sandbox.

The full set of credentials is returned on `GET /playgrounds/{id}`.

## Two Ways Playgrounds Arise

| Flow                                                                | Caller                                     | When                                                                              |
| ------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- |
| Explicit `POST /playgrounds`                                        | Benchmark authors, interactive exploration | You want to poke at an environment without running a full benchmark               |
| Implicit from `POST /benchmark-runs` (or `POST /v1/benchmark-runs`) | The run machinery                          | Verial provisions a playground for you and passes its endpoints back to the agent |

If you are running a benchmark end to end via the v1 API, you do not need to create playgrounds yourself. See the [Quick Start](/guides/quickstart).

## Teardown and Retention

Tear down a playground explicitly via `POST /playgrounds/{id}/teardown`, or let the benchmark run do it for you when the final task run completes. Teardown releases the live resources (so phone numbers are not held forever and FHIR stores are not billed indefinitely) but preserves:

* Every [Interaction](/guides/concepts/interactions) recorded during the run.
* Every sandbox event row (FHIR request log, HL7 outbound, portal form submits).
* The task runs, criterion runs, and scored results.

## Creating a Playground

```bash theme={null}
# Create the playground
curl -X POST https://api.verial.ai/playgrounds \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environment_id": "'"$ENVIRONMENT_ID"'"}'
# → save the returned id as $PLAYGROUND_ID

# Fetch full details including each sandbox's credentials
curl "https://api.verial.ai/playgrounds/$PLAYGROUND_ID" \
  -H "Authorization: Bearer $VERIAL_API_KEY"

# Do your work against the sandbox credentials returned above...

# Release resources when finished
curl -X POST "https://api.verial.ai/playgrounds/$PLAYGROUND_ID/teardown" \
  -H "Authorization: Bearer $VERIAL_API_KEY"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Sandboxes" icon="box" href="/guides/concepts/sandboxes">
    The running simulator instances inside a playground.
  </Card>

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