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

# Create a sandbox

> Choose environments, load starting state, wait for readiness, and handle partial failure safely.

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

```bash theme={null}
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:

```bash theme={null}
archal session wait <session-id> --until ready
```

## With TypeScript

```ts theme={null}
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.