Skip to main content
By default a machine can reach anything on the internet. An egress allowlist narrows that to the hosts and addresses you name. Everything else is refused at the edge of the machine, before it leaves the host. The allowlist is set from the outside: the machine’s Networking tab in the console, boxd machine egress on your laptop, or the SDKs. There is deliberately no way to change it from inside the machine. A process with root in the machine cannot widen its own allowlist. The allowlist is one of two egress controls. See Egress control for how it combines with host-bound secrets, forks, snapshots and isolation.

​
Entries

An entry is one of: Entries are bare hosts and addresses, without a scheme, port, or path. Wildcards are allowed when every host under the domain belongs to one party. *.npmjs.org only reaches hosts npm runs. They are refused on domains where anyone can get a subdomain, because that opens a way out to a host an attacker controls:
  • *.amazonaws.com would admit every S3 bucket.
  • *.vercel.app would admit every Vercel deployment.
  • The same goes for *.cloudfront.net, *.herokuapp.com, *.workers.dev, *.github.io, *.pages.dev and other shared-hosting or CDN domains.
Name the exact host instead, such as my-bucket.s3.amazonaws.com. Top-level wildcards like *.com are refused as well. Addresses must be public. Private, link-local, loopback and multicast ranges are refused, as is anything overlapping them, 0.0.0.0/0 included. IPv6 is refused too, because machines have no IPv6 egress.

​
How it works

Web requests (HTTP and HTTPS) are admitted by the hostname they name, so api.stripe.com works whichever address it resolves to. Everything else, an SSH connection or a database port for example, is admitted by destination address. The addresses of an allowlisted name count as allowlisted too, so a plain curl to an allowlisted host works without you listing its addresses. What a blocked request sees depends on the protocol: HTTP gets a 403, HTTPS has its connection closed during the handshake, and anything else is dropped. The hosts of any host-bound secret the machine holds are always admitted, on top of the list, so a secret bound to api.stripe.com keeps working under an allowlist that does not name it.

​
Set it

From your laptop:
The list you pass is the complete new allowlist. It replaces the old one. An empty allowlist means unrestricted, which is how every machine starts. In the console, open the machine, then Networking, then Edit next to the egress allowlist. A change takes effect within a second on a running machine, without a restart, and shows up in the console, the CLI and the SDKs at once.

​
Read it from inside the machine

The machine can read its own policy but not change it. Inside a machine:

​
From the SDKs

Each call replaces the whole list.

​
What to use it for

An allowlist turns a machine into a place where an agent or a job can run with a known set of destinations: the model provider, your own API, the package registry. Combine it with an isolated machine and with host-bound secrets, and the machine can neither reach what it should not nor leak a credential to where it should not go. See Sandboxes.