Create a sandbox - Archal

Create only the environments needed by one test boundary. A smaller sandbox is faster to understand, cheaper to run, and easier to clean up.

With the CLI

archal session create github slack \
  --state github=github-state.json \
  --state slack=slack-state.json \
  --ttl 1800

The CLI waits until every environment is ready unless --detach is present. Detached creation returns after durable provisioning begins, then you can run:

archal session wait <session-id> --until ready

With TypeScript

const sandbox = await archal.createSession(
  {
    environments: ['github', 'slack'],
    ttlSeconds: 1800,
    initialState: {
      github: { format: 'json', value: githubState },
      slack: { format: 'json', value: slackState },
    },
  },
  { idempotencyKey: 'incident-flow-001' },
);

createSession waits for readiness and attempts cleanup if readiness fails. Use startSession when your process needs the sandbox ID before the wait.

Creation rules

Every requested environment must be enabled for the workspace key.
State is validated before the sandbox becomes ready.
One invalid state payload fails the whole create request and triggers cleanup.
Reusing an idempotency key with the same request returns the original result.
Reusing it with a different request returns a conflict.
Failed provisioning and cold-start time are not billed.

The CLI creates a fresh idempotency key when you omit the option. Supply --idempotency-key only when your caller needs to retry the exact same create request after an uncertain response. Read expiresAt and the optional lease fields from the response. Server and plan policy can reduce a requested TTL.

⌘I