> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox environment configuration

> Set size, kind, metadata, environment values, and a credential profile through sandbox environment configuration.

Use sandbox environment configuration to set size, lifetime, environment values, metadata, and credentials when you create a machine. A template supplies the starting image; each machine has its own configuration.

## Set size and kind

```bash theme={null}
bead create --template agents --size small --kind temporary --timeout 900
bead create --template devbox --size small --kind persistent --idle-timeout 900
```

`--timeout` belongs to temporary machines. `--idle-timeout` belongs to persistent machines. See [machine lifetime](https://docs.bead.run/run-work/lifetime.md).

## Set environment and metadata

The create API accepts `envVars` and `metadata` maps. Save this as `create.json`:

```json theme={null}
{
  "templateID":"base",
  "size":"small",
  "kind":"temporary",
  "timeout":300,
  "envVars":{"APP_MODE":"test"},
  "metadata":{"name":"test-job"}
}
```

```bash theme={null}
bead api POST /v2/sandboxes --input create.json
```

Use metadata to describe the machine. Plain environment values can persist in files and captured process memory. Supply AI credentials through a profile and keep secrets out of reusable build inputs.

## Attach a credential profile

```bash theme={null}
bead create --template agents --size small --profile PROFILE_UUID --timeout 900
```

The CLI selects the saved profile through `metadata["bead.credentialProfile"]`. MCP create also accepts a `profile` UUID. You can select a profile for a later [runner prompt](https://docs.bead.run/agents/runners.md).

OpenClaw and Hermes copy credentials once into native app storage and own subscription refresh after creation. Vault edits affect new app machines. See [credentials](https://docs.bead.run/agents/credentials.md).

## Choose retained state

Use a [ready snapshot](https://docs.bead.run/snapshots/overview.md) as `templateID` to restore prepared memory. It must keep its original CPU and memory size. For a different size, use a disk template to start a new machine.

Temporary machines can attach a supported [persistent volume](https://docs.bead.run/platform/volumes.md) with `volumeMounts`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.