Environments

What a box receives

Pick an environment at create time (--environment on prized box new, environment on POST /api/v1/boxes) or let the default apply. The box receives, in order:

Env vars and secret files stay live: a change reaches the box within seconds, for new login shells. Secret files travel over the box's authenticated channel, never in the launch configuration, and the CLI shows only their path and size.

The default environment

There is none until you mark one: --default when creating, or prized environments default <name>. A box created from the CLI or API without naming an environment then takes it (environment: null on the API opts out). A box from the dashboard's New box page, the box your plan launches, a restore, and a fork never inherit one.

Versions and upgrade

Every save that changes what a box inherits mints a new immutable version (a rename or new description does not), and a box keeps its version until you upgrade it. Names are unique in the workspace regardless of case: prod and Prod are one name.

environment ml        v1 ──── v2 ──── v3 (latest)
                       │        │
box kiwi (created v1)  ●────────┼──── upgrade ──▶ v3
box mango (created v2)          ●──── stays on v2 until upgraded

prized environments upgrade <name> pins boxes to the latest version:

Up to 50 versions are kept per environment; older ones no live box pins are pruned.

Safe for third parties

A box for someone else (a contractor, a demo, an agent you do not fully trust) should hold none of your credentials: switch on safe for third parties on its environment (prized environments set <name> --safe-for-third-parties true), or tick Restricted when creating one box. Four channels close:

Env vars still apply. A safe environment cannot carry secret files (safe_environment_has_secret_files), and a restricted box never receives any, at create or on any upgrade, whatever environment it runs.

Restricted is one-way: set at create (restricted: true, or a safe environment), by an upgrade onto a safe version, or inherited by a restore, and never unset. The three channels can also be closed one at a time on an environment without restricting the box.

Repos

A repo is owner/name (GitHub) or an https:// clone URL, with an optional branch, directory under your home (default: the repo name), and setup script run inside the clone. A blocking repo clones before the others and before the environment's setup script.

Clones are plain https, so no credential lands in .git/config, and an existing directory is left alone. For a private repo, clone on the box once gh is signed in there (Credentials), or ship a deploy key as a secret file and clone in the setup script.

Vars and secret files

Env vars are not secret: shell-identifier names, single-line values, shown in the CLI. Put anything sensitive in a secret or a secret file: up to 64 KiB at a path relative to your home (.aws/credentials, .npmrc), encrypted at rest, decrypted only for its box, written 0600 or the mode you set, up to 16 per environment.

Per-box vars

Set a box's own vars with env at create (POST /api/v1/boxes with {"env": {"NAME": "value"}}) or Variables on the box page's Settings tab (PATCH /api/v1/boxes/:id with {"env": {...}}, which replaces the set). A per-box var wins over an environment var of the same name. Environment plus per-box vars must fit the launch budget of about 16 KiB compressed; a create or PATCH that would not fit is refused with environment_too_large.

Limits

Every cap, the launch budget included, is on Limits.

CLI

prized environments (alias prized envs); every command takes --json.

The CLI's environment object carries the API row's fields in snake_case (safe_for_third_parties, secret_files, latest_version, versions with boxes counts).

Exit codes follow the CLI table: an unknown environment or a restricted-box refusal is CHECK_FAILED (5), a bad value USAGE (2), a taken name CONFLICT (6).

API

All routes take your session or a dcp_ CLI bearer, are scoped to your workspace, and take JSON bodies.

On the box routes, POST /api/v1/boxes takes environment (id or name; null = none; absent = your default), env: {K: V} and restricted; PATCH /api/v1/boxes/:id with {env} replaces the per-box vars; GET /api/v1/boxes/:id carries environment: {id, name, versionNo, latestVersionNo}, envVars and restricted.

Errors: 400 invalid_repo, invalid_file, invalid_env_var, invalid_env, too_many_repos, too_many_files, environment_too_large (also from the box create and PATCH), safe_environment_has_secret_files; 404 not_found; 409 name_taken; 409 box_restricted from the mount and phone-access routes.