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

# Core concepts

> Understand sandboxes, stateful environments, starting state, baselines, and scoped credentials.

## Sandbox

A sandbox is an isolated runtime containing one or more stateful environments.
Its state and credentials do not cross into another sandbox.

The API and CLI use `session` for the sandbox lifecycle. `sessionId` is the
stable API identifier for that sandbox.

## Stateful environment

A stateful environment represents one external service inside the sandbox.
It keeps data across requests and exposes provider-shaped REST, MCP, or both.
A Slack environment behaves like Slack within its documented surface. It is
not flattened into a generic Archal record API.

## Starting state

Starting state is explicit JSON, or SQL for Supabase, loaded before the
sandbox becomes ready. Every environment publishes five versioned samples.
You can use one unchanged, inspect and edit it, or validate custom state.

Archal does not ask an LLM to invent hidden state during provisioning.

## Baseline

The baseline is the state restored by reset. State loaded at creation becomes
the first baseline. Replacing state later also replaces that reset baseline.

State loading uses replacement semantics. Collections omitted from a JSON
payload can be cleared, so review a diff before replacing shared work.

## Provider-shaped connection

When an environment is ready, Archal returns:

* `apiBaseUrl` for provider-shaped REST calls
* `mcpUrl` when the environment supports MCP
* a short-lived `credentials.headers` map scoped to that sandbox and environment

The Archal workspace key controls the sandbox lifecycle. It is not accepted by
the provider data plane. The SDK applies the returned provider headers for you.

## Explicit before snapshot

A diff compares current JSON state with an explicit `before` value held by the
caller. It does not silently compare against the reset baseline. Capture state
before the mutation when you need a trustworthy change report.

## Sample

A sample is a versioned, hash-verified starting state. It also documents a
first read, representative mutation, expected changed paths, reset expectation,
and limitations. Sample validation does not prove complete upstream parity.

## Channel and availability

* **Public** is the standard GA channel.
* **Preview** means it is included for testing, but upstream coverage is incomplete.

The authenticated result of `archal environment list` or `GET /api/environments`
is the source of truth for current availability.