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

# Secrets

> Give sandboxes environment variables and secret files, for all sandboxes or for one sandbox only.

Boat injects two types of secret when a sandbox starts.

| Type | Inside the sandbox |
| - | - |
| Environment variables | Process env vars and shell exports |
| Secret files | Files under `/home/user`, at the relative path that you give |

Use secrets for app credentials, API keys, `.env` files and deployment tokens.

Do not put secrets in these places:

* Prompts.
* URLs.
* CLI arguments that can go into logs.
* Docker build args.
* Committed files.

## Set secrets

<CodeGroup>
  ```bash CLI theme={null}
  boat env set-var base STRIPE_KEY=sk_live_123
  boat env rm-var base STRIPE_KEY
  boat env set-file base backend/.env --from ./local.env
  cat ./local.env | boat env set-file base backend/.env
  boat env rm-file base backend/.env
  ```

  ```bash curl theme={null}
  curl -sS -X POST "$BOAT_API_BASE/secrets" \
    -H "Authorization: Bearer $BOAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"envContents":"STRIPE_KEY=sk_live_123\n","secretFiles":[{"path":"backend/.env","contents":"DATABASE_URL=postgres://...\n"}]}'
  ```

  ```ts TypeScript theme={null}
  // default environment
  await sandbox.updateSecrets({
    envContents: "STRIPE_KEY=sk_live_123\n",
    secretFiles: [
      { path: "backend/.env", contents: "DATABASE_URL=postgres://...\n" },
    ],
  });

  // any named environment
  await sandbox.updateEnvironment({
    environmentId: envId,
    envContents: "STRIPE_KEY=sk_live_123\n",
    secretFiles: [{ path: "backend/.env", contents: "DATABASE_URL=postgres://...\n" }],
  });
  ```

  ```python Python theme={null}
  from boat_sdk.models.secret_file import SecretFile
  from boat_sdk.models.secrets_update_request import SecretsUpdateRequest

  # default environment
  sandbox.update_secrets(SecretsUpdateRequest(
      env_contents="STRIPE_KEY=sk_live_123\n",
      secret_files=[SecretFile(path="backend/.env", contents="DATABASE_URL=postgres://...\n")],
  ))

  # any named environment
  sandbox.update_environment(env_id, UpdateSandboxEnvironmentRequest(
      env_contents="STRIPE_KEY=sk_live_123\n",
      secret_files=[SecretFile(path="backend/.env", contents="DATABASE_URL=postgres://...\n")],
  ))
  ```
</CodeGroup>

<Warning>
  The `/secrets` endpoint **replaces** all secrets. It does not merge. Send every variable and secret file that you want to keep. Boat drops the ones that you leave out. The `boat env set-var` and `set-file` commands change one item at a time, so they do not have this risk.
</Warning>

## Secret file paths

Paths are relative to `/home/user`. There is no repository picker. To put a file inside a clone, start the path with the repository folder name.

This path:

```text theme={null}
ariana-ide-private/backend/.env
```

writes to:

```bash theme={null}
/home/user/ariana-ide-private/backend/.env
```

Boat skips absolute paths and paths that go outside `/home/user`.

## Variables for one sandbox

The variables of an environment apply to every sandbox that uses it. To give one sandbox its own values, pass `env` when you create it.

Boat merges the per-sandbox values over the environment's values. If the two have the same key, the per-sandbox value wins.

<CodeGroup>
  ```bash CLI theme={null}
  boat new --env DATABASE_URL=postgres://... --env FEATURE_FLAG=1
  ```

  ```bash curl theme={null}
  curl -sS -X POST "$BOAT_API_BASE/sandboxes" \
    -H "Authorization: Bearer $BOAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"ttlSeconds":3600,"env":{"DATABASE_URL":"postgres://...","FEATURE_FLAG":"1"}}'
  ```

  ```ts TypeScript theme={null}
  await sandbox.create({
    ttlSeconds: 3600,
    env: { DATABASE_URL: "postgres://...", FEATURE_FLAG: "1" },
  });
  ```

  ```python Python theme={null}
  sandbox.create(CreateSandboxRequest(
      ttl_seconds=3600,
      env={"DATABASE_URL": "postgres://...", "FEATURE_FLAG": "1"},
  ))
  ```
</CodeGroup>

| Rule | Limit |
| - | - |
| Key format | `[A-Za-z_][A-Za-z0-9_]*` |
| Key length | 128 characters maximum |
| Variables per sandbox | 100 maximum |
| Total size per sandbox | 64KB maximum |
| Reserved Boat-internal names (`ASCII_TOKEN`, `BOAT_ID`, and similar) | Rejected |

A fork gets the per-sandbox variables of its source sandbox. If the fork passes its own `env`, it does not get them.


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