What is a sandbox?

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

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

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

Create a sandbox

Choose environments, state, TTL, and an idempotency key.

Prepare starting state

Use one of 110 samples or validate your own JSON or SQL.

Call environments

Point existing provider clients at returned connections.

Inspect and reset

Capture state, compare mutations, and restore the baseline.

⌘I

​Why several environments share one sandbox

​What persists

​What the API calls it

​Lifecycle