Environments

An environment is the template a new Box inherits when it starts: which GitHub repositories are cloned, which secrets are injected, and which of your credentials the Box may use. Manage it from Dashboard > Environment or from the box env commands. Every account has one environment named base. You can add more, and name the one a Box should use when you create, resume, or fork it.

This page is about what goes into a Box. For running code inside one, see Setup & Scripts.

Safe for third parties

One switch decides the entire security posture of an environment.

On

For Boxes other people drive, such as your own end users. Nothing of yours is passed: no GitHub access, no secrets, no Box or Agents credentials, whatever the section toggles say. The Box is confined to itself and cannot act on your account or your other Boxes.

Off

For Boxes only you drive. The four section toggles below apply, so you choose exactly what goes in.

box env set base --safe-for-third-parties true

curl -sS -X PUT "$BOX_API_BASE/environments/$ENV_ID" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"safeForThirdParties":true}'

await box.updateEnvironment({
  environmentId: envId,
  updateBoxEnvironmentRequest: { safeForThirdParties: true },
});

box.update_environment(env_id, UpdateBoxEnvironmentRequest(safe_for_third_parties=True))

The --no-env flag (noEnv in the API) is the per-Box shortcut for the same guarantee and is kept forever. box new --no-env behaves exactly like starting in an environment marked safe for third parties. Prefer the environment when more than the occasional Box needs it: it holds for every Box that uses it, and it survives forks and resumes without your code passing a flag.

What a normal Box receives

To know what this protects you from, here is what a Box gets from your account when nothing is withheld.

	Passed in
Environment variables	Your environment’s variables, your GitHub token, and your model credentials if you configured agents (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `CHATGPT_ACCOUNT_ID`), plus neutral Box-internal vars (`BOX_ID`, a machine-scoped `ASCII_TOKEN`)
Credential files	Your secret files, the GitHub CLI login (`~/.config/gh/hosts.yml`), git credentials in cloned repos, Claude and Codex logins (`~/.claude/.credentials.json`, `~/.codex/auth.json`), the in-box Box CLI token (`~/.config/ascii/box/config.json`), and the shell environment the box exports to SSH sessions

A protected Box receives none of that. It keeps only the neutral Box-internal vars and whatever you pass with env.

Converting an existing Box

box resume <id> --no-env and box fork <id> --no-env convert a Box whose snapshot came from a normal one. Before the Box 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-box Box CLI token, and every secret file you configured. authorized_keys and known_hosts are kept so the Box stays reachable. Credentials the platform never wrote are left alone: aws, gcloud, .netrc, .npmrc, and Docker logins added inside the Box all stay. While the scrub runs, SSH and desktop return a retryable box_securing error. Conversion is one way: the Box stays protected afterwards.

The Claude and Codex credential files are removed even when the Box’s own user logged in with their personal account inside the Box. The scrub cannot tell whose they are. Back them up and restore them afterwards if they belong to the Box’s user.

What a Box can be given

With Safe for third parties off, four independent toggles decide what a Box receives. Each is a section in the dashboard; open a section to edit what is inside it.

Section	What the Box gets	Turning it off
GitHub repositories	Your repositories cloned in, plus the GitHub token	`gh` and `git push` stop working
Secrets	Your environment variables and secret files	Boxes drop them at their next start. What you typed is kept
Box credentials	A scoped Box API key, so the Box can snapshot, stop and resume itself	The Box cannot manage its own lifecycle
Agents credentials	The provider keys (Claude, Codex, and so on) from the Agents tab	Agents in the Box have no login

box env set base --github true --secrets true --box-credentials false --agents-credentials true

curl -sS -X PUT "$BOX_API_BASE/environments/$ENV_ID" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"passGithub":true,"passSecrets":true,"passBoxCredentials":false,"passAgentsCredentials":true}'

await box.updateEnvironment({
  environmentId: envId,
  updateBoxEnvironmentRequest: {
    passGithub: true,
    passSecrets: true,
    passBoxCredentials: false,
    passAgentsCredentials: true,
  },
});

box.update_environment(env_id, UpdateBoxEnvironmentRequest(
    pass_github=True,
    pass_secrets=True,
    pass_box_credentials=False,
    pass_agents_credentials=True,
))

Versions, and when a Box moves between them

This is the part worth reading twice.

you save a change  ──▶  a new version is created
                            │
                            ├──▶ every Box that starts from now on gets it
                            │
                            └──▶ Boxes already running: nothing happens
                                     │
                                     └──▶ they move only when you upgrade

A Box 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 Box. There is no automatic upgrade, no background rollout, and no scheduled window: a Box moves when you press Upgrade in the dashboard or run box env upgrade, and at no other time. box info tells you which one a Box is on, as environment and environmentVersion. Compare that number against the environment’s latest in box env list: a Box below it is still running the older configuration, which is usually the answer to “I added that secret, why does my Box not have it?”

box info bx_f7k2q9hd     # env:  prod (v2)
box env list             # prod  latest v3   -> this Box is one upgrade behind

Upgrading applies the new configuration and removes any secret the new version withholds. Live Boxes are cleaned and updated immediately; stopped Boxes pick it up when they resume.

Upgrading is not reversible on that Box’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 Boxes 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 Box requires it — you can also skip the connection entirely and use gh with your own token inside the Box.

Each repository carries a base branch, an optional setup script, and optional pre-commit hooks. Box 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 Box changes it.

box env add-repo base octocat/hello-world --branch develop
box env rm-repo base octocat/hello-world

repo_id=$(curl -sS "$BOX_API_BASE/repos?sync=true&q=hello-world" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  | jq -r '.installations[0].repositories[0].databaseId')

curl -sS -X POST "$BOX_API_BASE/repos" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"repositoryId\":\"$repo_id\",\"baseBranch\":\"develop\"}"

const repos = await box.repos({ sync: true, q: "hello-world" });
const repo = repos.installations.flatMap((i) => i.repositories)[0];

await box.selectRepo({
  repoSelectionRequest: { repositoryId: repo.databaseId, baseBranch: "develop" },
});

from ascii_box_sdk.models.repo_selection_request import RepoSelectionRequest

repos = box.repos(sync=True, q="hello-world")
repo = repos.installations[0].repositories[0]

box.select_repo(RepoSelectionRequest(repository_id=repo.database_id, base_branch="develop"))

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.

GitHub repository	Box path
`ariana-dot-dev/ariana-ide-private`	`/home/user/ariana-ide-private`
`octocat/hello-world`	`/home/user/hello-world`

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 Box starts.

Environment variables, readable as process env vars and shell exports inside the Box.
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.

box env set-var base STRIPE_KEY=sk_live_123
box env rm-var base STRIPE_KEY
box env set-file base backend/.env --from ./local.env
cat ./local.env | box env set-file base backend/.env
box env rm-file base backend/.env

curl -sS -X POST "$BOX_API_BASE/secrets" \
  -H "Authorization: Bearer $BOX_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 box.updateSecrets({
  secretsUpdateRequest: {
    envContents: "STRIPE_KEY=sk_live_123\n",
    secretFiles: [
      { path: "backend/.env", contents: "DATABASE_URL=postgres://...\n" },
    ],
  },
});

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

from ascii_box_sdk.models.secret_file import SecretFile
from ascii_box_sdk.models.secrets_update_request import SecretsUpdateRequest

# default environment
box.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
box.update_environment(env_id, UpdateBoxEnvironmentRequest(
    env_contents="STRIPE_KEY=sk_live_123\n",
    secret_files=[SecretFile(path="backend/.env", contents="DATABASE_URL=postgres://...\n")],
))

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 box 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:

ariana-ide-private/backend/.env

writes to:

/home/user/ariana-ide-private/backend/.env

Absolute paths, and paths that escape /home/user, are skipped.

Per-Box variables

An environment’s variables apply to every Box using it. To give one Box its own values, pass env when you create it. Per-Box values are merged over the environment’s, so a per-Box key wins a name collision.

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

curl -sS -X POST "$BOX_API_BASE/boxes" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":3600,"env":{"DATABASE_URL":"postgres://...","FEATURE_FLAG":"1"}}'

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

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

Keys must match [A-Za-z_][A-Za-z0-9_]* (max 128 chars), at most 100 variables and 64KB per Box. Reserved Box-internal names (ASCII_TOKEN, BOX_ID, and similar) are rejected. A forked Box inherits its source’s per-Box variables unless the fork passes its own env.

Named environments

There is always exactly one default, and it is what a Box uses when you do not name one.

box env list
box env info staging
box env new staging
box env rename staging prod
box env default prod
box env rm staging
box env upgrade prod

curl -sS "$BOX_API_BASE/environments" -H "Authorization: Bearer $BOX_API_KEY"

curl -sS -X POST "$BOX_API_BASE/environments" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"staging"}'

curl -sS -X PUT "$BOX_API_BASE/environments/$ENV_ID" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod","isDefault":true,"safeForThirdParties":true}'

curl -sS -X POST "$BOX_API_BASE/environments/$ENV_ID/upgrade" \
  -H "Authorization: Bearer $BOX_API_KEY"

curl -sS -X DELETE "$BOX_API_BASE/environments/$ENV_ID" \
  -H "Authorization: Bearer $BOX_API_KEY"

const { environments } = await box.environments();
const staging = await box.createEnvironment({
  createBoxEnvironmentRequest: { name: "staging" },
});

await box.updateEnvironment({
  environmentId: envId,
  updateBoxEnvironmentRequest: { name: "prod", isDefault: true, safeForThirdParties: true },
});

await box.upgradeEnvironment({ environmentId: envId });
await box.deleteEnvironment({ environmentId: envId });

from ascii_box_sdk.models.create_box_environment_request import CreateBoxEnvironmentRequest
from ascii_box_sdk.models.update_box_environment_request import UpdateBoxEnvironmentRequest

envs = box.environments()
staging = box.create_environment(CreateBoxEnvironmentRequest(name="staging"))

box.update_environment(env_id, UpdateBoxEnvironmentRequest(
    name="prod", is_default=True, safe_for_third_parties=True,
))

box.upgrade_environment(env_id)
box.delete_environment(env_id)

Deleting is a soft delete. Boxes pinned to its versions keep running; new Boxes can no longer use it. upgradeEnvironment accepts an optional list of Box ids to restrict the upgrade; omit it to move every Box of yours that is on an older version.

Using an environment for a Box

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.

box new --environment staging
box resume bx_f7k2q9hd --environment staging
box fork bx_f7k2q9hd --environment staging

curl -sS -X POST "$BOX_API_BASE/boxes" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":3600,"environment":"staging"}'

await box.create({ createBoxRequest: { ttlSeconds: 3600, environment: "staging" } });
await box.resume({ boxId, resumeRequest: { environment: "staging" } });
await box.fork({ boxId, forkRequest: { environment: "staging" } });

box.create(CreateBoxRequest(ttl_seconds=3600, environment="staging"))
box.resume(box_id, ResumeRequest(environment="staging"))
box.fork(box_id, ForkRequest(environment="staging"))

--environment and --env are different things. --environment staging picks which environment the Box uses. --env KEY=value sets one variable on that single Box, on top of whatever the environment gives it.

​Safe for third parties

On

Off

​What a normal Box receives

​Converting an existing Box

​What a Box can be given

​Versions, and when a Box moves between them

​Repositories

​Where repositories land

​Secrets

​Secret file paths

​Per-Box variables

​Named environments

​Using an environment for a Box

​Related

Safe for third parties

What a normal Box receives

Converting an existing Box

What a Box can be given

Versions, and when a Box moves between them

Repositories

Where repositories land

Secrets

Secret file paths

Per-Box variables

Named environments

Using an environment for a Box

Related