Skip to main content
Set an environment variable or a secret once for your organization, and boxd injects it into the machines in the var’s scope. The default scope is 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 opaque bxds_... 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:
In the SDKs the list you pass is the complete set, so pass it again when rotating a value. Setting the secret again without it makes it a plain secret. Inside the machine, 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.
So you can give a machine the use of a key without giving it the key. That fits agentic SaaS and sandboxes: code you do not fully trust, or an agent acting for a customer, can call the customer’s API and still cannot walk away with the credential. For the substitution to happen, HTTPS to a bound host is handled by boxd with a certificate the machine already trusts. Standard tools and libraries work unchanged. A tool that pins certificates or ships its own CA bundle will refuse the connection to a bound host. Give it the system trust store or leave that secret unbound. The hosts of a host-bound secret are always reachable from the machine, on top of any egress allowlist it has. Pair the two to confine what the machine can reach at all. See Egress control.

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:

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 exec commands.
  • The pre-installed coding agents.
  • 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. Where one name is set in several places, the most private wins: the machine’s spec (its own 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.