# Archal testing sandboxes

Archal creates isolated testing sandboxes for AI agents, CI jobs, QA, and software integrations. A sandbox contains one or more stateful, provider-shaped environments.

The CLI and API call a sandbox a session. Its stable identifier is `sessionId`.

## Authentication

Create a workspace key in Dashboard > API keys.

- Control plane: `Authorization: Bearer $ARCHAL_API_KEY`
- Provider data plane: use the exact `environments.<id>.credentials.headers` returned after readiness

Never send the workspace key, `x-archal-key`, or a real provider token to an environment URL. The data plane accepts only the returned credential scoped to that session and environment.

## Lifecycle

1. `GET /api/environments` to inspect capabilities and state contracts
2. `POST /api/sessions` with a required `Idempotency-Key`, `environments`, and optional `initialState`
3. Poll `GET /api/sessions/{sessionId}` until every environment is ready
4. Call each returned `apiBaseUrl` or `mcpUrl` with its returned credential headers
5. Inspect state or diff it against an explicit caller-held before snapshot
6. Reset to the declared baseline when needed
7. `DELETE /api/sessions/{sessionId}` in cleanup

The catalog contains exactly 22 environments and 110 versioned samples, five per environment. All current environments accept explicit JSON. Supabase also accepts guarded SQL, and its five published samples are SQL. Prompt-based hidden state generation is not supported.

## Clients

- Install: `npm install --global archal@0.11.2`
- TypeScript: `ArchalEnvironmentClient` from the `archal` package
- CLI discovery: `archal environment ...` and `archal sample ...`
- CLI lifecycle: `archal session ...` and `archal state ...`
- Hosted lifecycle MCP: `https://archal.ai/api/mcp`
- Raw HTTP: `https://api.archal.ai`

## Pricing

An eligible new user receives $5 for the first free workspace after signup and $15 after its first sandbox is ready. Creating another workspace does not repeat the offer. The credit does not renew. On the Usage offering, each ready environment costs $0.10 per minute, prorated by the billed second.

## Documentation

- https://docs.archal.ai/introduction
- https://docs.archal.ai/quickstart
- https://docs.archal.ai/manual-quickstart
- https://docs.archal.ai/concepts
- https://docs.archal.ai/pricing-usage
- https://docs.archal.ai/sandboxes/overview
- https://docs.archal.ai/sandboxes/create
- https://docs.archal.ai/sandboxes/starting-state
- https://docs.archal.ai/sandboxes/call
- https://docs.archal.ai/sandboxes/inspect-reset
- https://docs.archal.ai/sandboxes/lifecycle-usage
- https://docs.archal.ai/environments/overview
- https://docs.archal.ai/environments/apify
- https://docs.archal.ai/environments/calcom
- https://docs.archal.ai/environments/clickup
- https://docs.archal.ai/environments/customerio
- https://docs.archal.ai/environments/datadog
- https://docs.archal.ai/environments/discord
- https://docs.archal.ai/environments/github
- https://docs.archal.ai/environments/gitlab
- https://docs.archal.ai/environments/google-workspace
- https://docs.archal.ai/environments/hubspot
- https://docs.archal.ai/environments/jira
- https://docs.archal.ai/environments/linear
- https://docs.archal.ai/environments/ownerrez
- https://docs.archal.ai/environments/pricelabs
- https://docs.archal.ai/environments/ramp
- https://docs.archal.ai/environments/sentry
- https://docs.archal.ai/environments/slack
- https://docs.archal.ai/environments/stripe
- https://docs.archal.ai/environments/supabase
- https://docs.archal.ai/environments/tavily
- https://docs.archal.ai/environments/unipile
- https://docs.archal.ai/environments/webflow
- https://docs.archal.ai/integrations/coding-agents
- https://docs.archal.ai/integrations/javascript
- https://docs.archal.ai/integrations/cli
- https://docs.archal.ai/integrations/mcp-clients
- https://docs.archal.ai/integrations/ci
- https://docs.archal.ai/api/authentication
- https://docs.archal.ai/api/lifecycle
- https://docs.archal.ai/api/starting-state
- https://docs.archal.ai/api/call-environment
- https://docs.archal.ai/api/reset-state
- https://docs.archal.ai/api/errors-retries
- https://docs.archal.ai/api/idempotency
- https://docs.archal.ai/api/limits-usage
- https://docs.archal.ai/security
- https://docs.archal.ai/api-reference/openapi.json