Skip to main content
An environment is the template a new Sandbox inherits when it starts: which GitHub repositories are cloned, which secrets are injected, and which of your credentials the sandbox may use. Manage it from Dashboard > Environment or from the 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.
The --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.
The Claude and Codex credential files are removed even when the sandbox’s own user logged in with their personal account inside the sandbox. The scrub cannot tell whose they are. Back them up and restore them afterwards if they belong to the sandbox’s user.

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.
A Sandbox takes the latest version at the moment it starts, and keeps that exact version for the rest of its life. Saving never reaches into a running sandbox. There is no automatic upgrade, no background rollout, and no scheduled window: a sandbox moves when you press Upgrade in the dashboard or run 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?”
Upgrading applies the new configuration and removes any secret the new version withholds. Live Sandboxes are cleaned and updated immediately; stopped sandboxes pick it up when they resume.
Upgrading is not reversible on that sandbox’s disk. A secret the new version withholds is deleted from the machine, not hidden. Re-pinning to the older version does not bring back a secret file the newer version dropped.
The Versions panel lists every version and how many sandboxes sit on each, so you can see what is still running old configuration.

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.
Each repository carries a base branch and an optional setup script. Boat clones that branch as it is, and never creates a branch for you, forks included. Repositories stay on the base branch unless you or something inside the sandbox changes it.
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 is user 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/user at the relative path you give.
Use these for app credentials, API keys, .env files and deployment tokens. Do not pass secrets in prompts, URLs, CLI arguments that may be logged, Docker build args, or committed files.
The /secrets endpoint is a full replacement, not a merge. Send every variable and secret file that should remain, or the ones you leave out are dropped. The granular boat env set-var and set-file commands change one item at a time and do not have this hazard.

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:
writes to:
Absolute paths, and paths that escape /home/user, are skipped.

Per-Sandbox variables

An environment’s variables apply to every sandbox using it. To give one sandbox its own values, pass env when you create it. Per-Sandbox values are merged over the environment’s, so a per-Sandbox key wins a name collision.
Keys must match [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.
Deleting is a soft delete. Sandboxes pinned to its versions keep running; new Sandboxes can no longer use it. 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.

Using an environment for a sandbox

Pass the name when you create, resume, or fork. Omit it to use your default. Unknown names are rejected outright, before anything is created or changed, so a typo costs you nothing. Environments are never created implicitly.
--environment and --env are different things. --environment staging picks which environment the sandbox uses. --env KEY=value sets one variable on that single sandbox, on top of whatever the environment gives it.