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

# Secrets & Environment Variables

> Store configuration and credentials for your sandboxes.

Pocketenv has two ways to pass configuration into a sandbox:

|                    | Environment Variables | Secrets                 |
| ------------------ | --------------------- | ----------------------- |
| **Stored as**      | Plaintext             | Encrypted (libsodium)   |
| **Visible in API** | Yes                   | Redacted                |
| **Use for**        | Non-sensitive config  | Passwords, tokens, keys |

## Environment variables

### CLI

```bash theme={"theme":{"light":"catppuccin-latte","dark":"laserwave"}}
# Set a variable
pocketenv env put my-sandbox DATABASE_URL "postgres://localhost/mydb"
pocketenv env put my-sandbox NODE_ENV "production"

# List all variables
pocketenv env list my-sandbox
pocketenv env ls my-sandbox      # alias

# Delete a variable
pocketenv env delete <variable-id>
pocketenv env rm <variable-id>   # alias
```

### SDK

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"laserwave"}}
await sandbox.env.put("DATABASE_URL", "postgres://localhost/mydb");
await sandbox.env.put("NODE_ENV", "production");

const vars = await sandbox.env.list();
// [{ id: "...", name: "DATABASE_URL", value: "postgres://..." }, ...]

await sandbox.env.delete(varId);
```

## Secrets

Secrets are encrypted at rest using libsodium. The value is never returned in API responses — only a redacted placeholder is shown.

### CLI

```bash theme={"theme":{"light":"catppuccin-latte","dark":"laserwave"}}
# Set a secret (you'll be prompted for the value)
pocketenv secret put my-sandbox API_KEY

# List secret names (values are never shown)
pocketenv secret list my-sandbox
pocketenv secret ls my-sandbox   # alias

# Delete
pocketenv secret delete <secret-id>
pocketenv secret rm <secret-id>  # alias
```

### SDK

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"laserwave"}}
await sandbox.secret.put("API_KEY", process.env.API_KEY!);
await sandbox.secret.put("STRIPE_SECRET", "sk_live_...");

const secrets = await sandbox.secret.list();
// [{ id: "...", name: "API_KEY" }]  ← value is never returned

await sandbox.secret.delete(secretId);
```

## Setting variables at sandbox creation

You can bake env vars and secrets into a sandbox at creation time via the SDK builder:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"laserwave"}}
const sandbox = await Sandbox.builder("openclaw")
  .name("my-app")
  .env("NODE_ENV", "production")
  .env("PORT", "3000")
  .secret("DATABASE_URL", process.env.DATABASE_URL!)
  .secret("API_KEY", process.env.API_KEY!)
  .create();
```

## API

For direct API usage see:

* [Add Variable](/api-reference/variable/add)
* [List Variables](/api-reference/variable/list)
* [Add Secret](/api-reference/secret/add)
* [List Secrets](/api-reference/secret/list)