Skip to main content
boxd has two egress controls. Both are set from outside the machine and enforced outside it, so nothing running inside (root included) can loosen them:
  • Egress allowlist. The hosts and addresses one machine may reach. Everything else is blocked.
  • Host-bound secrets. The machine only ever holds a placeholder, and the real value is inserted into HTTPS requests on their way out, only to the hosts you name.
Use them together for an agent that needs one API and nothing else, or separately.

​
The allowlist

A machine starts unrestricted. Give it an allowlist and it can reach only the hostnames, wildcards, IPv4 addresses and ranges on it:
An allowlist of just none cuts the machine off from the internet entirely. DNS follows the allowlist: a lookup of a name the machine may not reach is refused, so it can’t carry data out either. A change takes effect within a second on a running machine, without a restart. A machine spec can give a machine its allowlist from birth, with egress, so it never runs unrestricted. See Egress allowlist for what an entry can be, how requests are matched, and the console and SDK forms.

​
Host-bound secrets

A secret is normally injected into the machine as its real value. Bound to a host, it is not:
Inside the machine STRIPE_KEY is an opaque string starting with bxds_. An HTTPS request to api.stripe.com that carries it, in the URL, a header or the body, arrives at Stripe with the real key, and where Stripe’s response repeats the value, the machine gets the placeholder instead. A plain HTTP request, or a request anywhere else, carries the useless placeholder. See Env vars and secrets for the details, rotation, wildcards, and the console and SDK forms. The hosts of any host-bound secret a machine holds are always reachable from it, allowlist or not.

​
Forks, snapshots, and isolation

  • Forks. A fork inherits its source machine’s allowlist. A confined machine’s fork comes up confined.
  • Snapshots. A machine created from a snapshot starts unrestricted, unless its machine spec lists egress: a snapshot keeps its machine’s spec, and a spec’s egress becomes the allowlist of a machine created from it. Otherwise set one after you create the machine if you need it.
  • Secrets. Host-bound secrets are set once per organization and apply to every machine in the secret’s scope, including forks and machines created from snapshots.
  • Isolation. --isolated and the allowlist are independent. Isolation cuts a machine off from your other machines and your boxd account. The allowlist cuts it off from the internet. A sandbox for untrusted code usually wants both. See Sandboxes.
  • Isolated machines. On an isolated machine, host-bound secrets arrive in exec and SSH sessions only, like every env var and secret. Nothing is injected at boot.

​
Where to set them

A machine spec sets the allowlist from birth with egress, and lists the secrets a machine gets with secrets. Neither can be set from inside a machine. The in-machine CLI can only read the policy, and an SDK running inside a machine on the machine’s own credentials can’t change that machine’s allowlist or the secrets its spec lists. Make those changes from outside, with an API key or in the console. See Egress allowlist.