Env vars & secrets

Set environment variables and secrets once, at the organization level, and boxd injects them into every machine you own. This means into login shells, into the environment your boxd machine exec commands and coding agents run in, and into services your machine starts at boot. Every machine picks the values up on its own, without .env files to copy around. There are two kinds:

	`boxd env`	`boxd env … --secret`
For	non-sensitive config	tokens, API keys, passwords
At rest	cleartext	sealed
Readable back	yes (`list` shows values)	never (`list` shows names and scope only)

Both are injected into your machines the same way. The difference is what happens at rest. Env var values are stored in cleartext and shown by list. Secret values are sealed and never returned by the API, not even to you. To change a secret you re-set it. Manage them from the CLI, the in-VM CLI, or the console.

Environment variables

boxd env set DATABASE_URL postgres://user:pass@db.example.com/app   # create or update
boxd env list                                                       # list, values shown (alias: ls)
boxd env rm DATABASE_URL                                            # remove (alias: remove)

Secrets

boxd env set OPENAI_API_KEY sk-... --secret   # create or rotate (sealed at rest)
boxd env list                                 # secrets print as (sealed), never the value (alias: ls)
boxd env rm OPENAI_API_KEY --secret           # remove (alias: remove)
boxd env scope OPENAI_API_KEY private         # move a secret to a different scope (value preserved)

Naming

Names must be valid environment identifiers, made of letters, digits, and underscores, starting with a letter or an underscore. The BOXD_* prefix is reserved for boxd’s own variables.

Scope

The --scope flag decides which of the org’s machines receive the variable:

Scope	Applies to
`shared`	shared org machines only (default)
`private`	your private, org-billed machines only
`all`	both

boxd env set API_BASE https://api.internal --scope all
boxd env set DEPLOY_KEY ... --scope private --secret

How they reach a machine

On boot, and again on every login shell, boxd resolves the env vars and secrets in scope for that machine and exports them. So they’re present for:

interactive shells (ssh <vm>.boxd),
boxd machine exec commands,
the pre-installed coding agents, and
services your machine starts at boot.

Add or rotate a value and new machines pick it up immediately. Already-running machines see it on their next boot profile refresh.

Getting started

Guides

Use cases

References

Env vars & secrets

Environment variables

Secrets

Naming

Scope

How they reach a machine

​Environment variables

​Secrets

​Naming

​Scope

​How they reach a machine

Environment variables

Secrets

Naming

Scope

How they reach a machine