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

# What is a sandbox?

> See how one isolated sandbox can hold several stateful provider environments.

An Archal sandbox is the isolation boundary for one test workflow. It can hold
one stateful environment or several that need to work together.

```text theme={null}
Sandbox sbx_01
├── GitHub environment
├── Slack environment
└── Datadog environment
```

Each environment keeps its own provider-shaped state. The sandbox groups their
lifecycle, expiry, isolation, and cleanup.

## Why several environments share one sandbox

A real agent rarely touches one service in isolation. An incident workflow may
read a Datadog monitor, open a GitHub issue, and post a Slack update. Putting
the three environments in one sandbox gives that test one coherent boundary
without sharing state with another run.

Customers are billed for ready environments, not the number of underlying
runtime containers. In this example, three ready environments accrue three
environment-minutes for every minute they remain ready.

## What persists

State persists across provider calls until you load replacement state, reset,
or destroy the sandbox. A second sandbox begins from its own declared state and
cannot read the first sandbox.

## What the API calls it

The public lifecycle schema was built around `sessionId`, and the CLI uses
`archal session ...`. A session is not a second product object. It is the API
record for the sandbox customers create and use.

## Lifecycle

1. Create the sandbox with environment IDs and optional starting state.
2. Wait until every selected environment reports `ready`.
3. Use each returned URL and scoped credential.
4. Inspect, diff, or reset state as the test runs.
5. Renew only while useful work continues.
6. Destroy the sandbox when the workflow ends.

<CardGroup cols={2}>
  <Card title="Create a sandbox" icon="plus" href="/sandboxes/create">
    Choose environments, state, TTL, and an idempotency key.
  </Card>

  <Card title="Prepare starting state" icon="database" href="/sandboxes/starting-state">
    Use one of 110 samples or validate your own JSON or SQL.
  </Card>

  <Card title="Call environments" icon="arrow-right" href="/sandboxes/call">
    Point existing provider clients at returned connections.
  </Card>

  <Card title="Inspect and reset" icon="rotate" href="/sandboxes/inspect-reset">
    Capture state, compare mutations, and restore the baseline.
  </Card>
</CardGroup>