shared, which reaches the org’s shared machines. Values arrive in login shells, in the environment your boxd machine exec commands and coding agents run in, and in services your machine starts at boot. Every machine in scope picks the values up on its own, without .env files to copy around, in every region your org uses.
There are two kinds:
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-machine CLI, or the console. The commands on this page are the laptop forms.
Environment variables
Secrets
Host-bound secrets
A secret can be bound to the hosts it may be sent to. The machine then only holds an opaquebxds_... placeholder, and the real value is substituted into HTTPS requests to those hosts on the way out, and nowhere else.
--domains takes hostnames or wildcards such as *.stripe.com, comma-separated or repeated. Provider-wide wildcards such as *.amazonaws.com are refused. The console offers the same on the Secrets page, as a hosts field on a secret and a Hosts column in the list.
The SDKs take domains on secrets.set:
STRIPE_KEY is the placeholder. An HTTPS request to api.stripe.com carrying it anywhere, in the URL, a header (Basic auth included) or the body, arrives at Stripe with the real key. There is nothing to configure in the machine. Your code uses the variable as it always did.
The value is substituted only over HTTPS, and only when both the server name the connection was opened for and the request’s own Host are hosts the secret is bound to. A plain HTTP request, or one to any other host, carries the placeholder as written. So does a request body over 16 MiB that has a Content-Length.
Responses from a bound host carry the placeholder too. Wherever the real value (8 characters or more) appears in a response’s headers or body exactly as it was sent, the machine receives the placeholder instead, so a server that echoes the request doesn’t hand the value to the machine. A value the server sends back re-encoded (base64, URL- or JSON-escaped) isn’t caught, and neither is one in a body compressed with anything but gzip or deflate. boxd asks the bound host for an uncompressed response.
The real value never enters the machine. That changes what a secret is:
- Nothing running inside can read it, log it, or send it elsewhere, whether that is an agent, a prompt injection, a compromised dependency, or a process with root.
env, shell history, and agent transcripts only ever contain the placeholder. - The placeholder is useless anywhere else. Sent to any host you did not name, it is a meaningless string.
- Rotating the value does not change the placeholder, so nothing inside needs to restart or know.
Naming
Names must be valid environment identifiers, made of letters, digits, and underscores, starting with a letter or an underscore. TheBOXD_* prefix is reserved for boxd’s own variables.
Scope
The--scope flag decides which of the org’s machines receive the variable:
Unattached secrets
Two more scopes are for secrets only. A secret in one of them reaches no machine by itself, only the machines whose machine spec lists it by name. That is how you give a token to the machines that need it and to no others.
Set them from the SDKs, the gRPC API, or the console’s Secrets page, which offers Unattached, org to owners and admins and Unattached, yours to everyone. The CLI’s
--scope does not take them.
list reports the org’s as unattached and yours as private-unattached, each with boundMachines (bound_machines): how many machines list it in their spec. A machine keeps a reference, not a copy, so rotating the secret reaches those machines, deleting it takes it away from them, and setting it again under the same name brings it back. An unattached secret can be bound to hosts like any other.
Env vars can’t use these scopes. A plain value one machine needs belongs in its spec’s env.
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 in:- Interactive shells (
ssh <machine>.boxd). boxd machine execcommands.- The pre-installed coding agents.
- Services your machine starts at boot.
env and the secrets it lists), then your private vars, then the org’s shared vars (on shared machines), then its all vars.
An isolated machine gets them in exec and SSH sessions only, never at boot. See Sandboxes.