boat env commands.
Every account has one environment named base. You can add more, and name the one a sandbox should use when you create, resume, or fork it.
This page is about what goes into a sandbox. For running code inside one, see Setup & Scripts.
Safe for third parties
One switch decides the entire security posture of an environment.On
For Sandboxes other people drive, such as your own end users. Nothing of yours is passed: no GitHub access, no secrets, no sandbox or Agents credentials, whatever the section toggles say. The Sandbox is confined to itself and cannot act on your account or your other sandboxes.
Off
For Sandboxes only you drive. The four section toggles below apply, so you choose exactly what goes in.
--no-env flag (noEnv in the API) is the per-Sandbox shortcut for the same guarantee and is kept forever. boat new --no-env behaves exactly like starting in an environment marked safe for third parties. Prefer the environment when more than the occasional sandbox needs it: it holds for every sandbox that uses it, and it survives forks and resumes without your code passing a flag.
What a normal Boat receives
To know what this protects you from, here is what a sandbox gets from your account when nothing is withheld.
A protected Boat receives none of that. It keeps only the neutral Boat-internal vars and whatever you pass with
env.
Converting an existing sandbox
boat resume <id> --no-env and boat fork <id> --no-env convert a sandbox whose snapshot came from a normal one. Before the sandbox becomes reachable, every owner secret the snapshot may carry is scrubbed: the managed ~/.bashrc blocks, ~/.config/gh/hosts.yml (plus a gh logout), ~/.git-credentials, ~/.ssh/id_* private keys, the Codex and Claude credential files, the in-sandbox Boat CLI token, and every secret file you configured. authorized_keys and known_hosts are kept so the sandbox stays reachable.
Credentials the platform never wrote are left alone: aws, gcloud, .netrc, .npmrc, and Docker logins added inside the sandbox all stay.
While the scrub runs, SSH and desktop return a retryable boat_securing error. Conversion is one way: the sandbox stays protected afterwards.
What a sandbox can be given
With Safe for third parties off, four independent toggles decide what a sandbox receives. Each is a section in the dashboard; open a section to edit what is inside it.Versions, and when a sandbox moves between them
This is the part worth reading twice.boat env upgrade, and at no other time.
boat info tells you which one a sandbox is on, as environment and environmentVersion. Compare that number against the environment’s latest in boat env list: a sandbox below it is still running the older configuration, which is usually the answer to “I added that secret, why does my sandbox not have it?”
Repositories
Repositories need a GitHub connection on your account. If you signed in with Google or an email code, open Dashboard > Environment and use Connect GitHub under GitHub repositories: it attaches GitHub to the account you already have, and you keep signing in the way you do now. Nothing else in Boat requires it: you can also skip the connection entirely and use
gh with your own token inside the sandbox.selectRepo and updateSecrets act on your default environment. To edit a named one, use the environment calls below.Where repositories land
On the hosted image the SSH user isuser and the work directory is /home/user. Each folder is named after the repository, not the owner/name pair.
With one repository, that folder is the project directory for agent tools. With several,
/home/user stays the parent workspace and each repository is a sibling folder.
Secrets
Two shapes, both injected when a sandbox starts.- Environment variables, readable as process env vars and shell exports inside the sandbox.
- Secret files, written under
/home/userat the relative path you give.
.env files and deployment tokens. Do not pass secrets in prompts, URLs, CLI arguments that may be logged, Docker build args, or committed files.
Secret file paths
Paths are relative to/home/user. There is no repository picker, so include the repository folder name to land a file inside a clone:
/home/user, are skipped.
Per-Sandbox variables
An environment’s variables apply to every sandbox using it. To give one sandbox its own values, passenv when you create it. Per-Sandbox values are merged over the environment’s, so a per-Sandbox key wins a name collision.
[A-Za-z_][A-Za-z0-9_]* (max 128 chars), at most 100 variables and 64KB per sandbox. Reserved Boat-internal names (ASCII_TOKEN, BOAT_ID, and similar) are rejected. A forked sandbox inherits its source’s per-Sandbox variables unless the fork passes its own env.
Named environments
There is always exactly one default, and it is what a sandbox uses when you do not name one.upgradeEnvironment accepts an optional list of sandbox ids to restrict the upgrade; omit it to move every sandbox of yours that is on an older version.