Skip to main content

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