Secrets - boat

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

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

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"}]}'

// 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" }],
});

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")],
))

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.

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:

ariana-ide-private/backend/.env

writes to:

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

boat new --env DATABASE_URL=postgres://... --env FEATURE_FLAG=1

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"}}'

await sandbox.create({
  ttlSeconds: 3600,
  env: { DATABASE_URL: "postgres://...", FEATURE_FLAG: "1" },
});

sandbox.create(CreateSandboxRequest(
    ttl_seconds=3600,
    env={"DATABASE_URL": "postgres://...", "FEATURE_FLAG": "1"},
))

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.

​Set secrets

​Secret file paths

​Variables for one sandbox

Set secrets

Secret file paths

Variables for one sandbox