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, the SDKs, or a machine spec. There is deliberately no way to change it from inside the machine. A process with root in the machine cannot widen its own allowlist, and an SDK running inside the machine on the machine’s own credentials is refused when it tries to change that machine’s allowlist, directly or through its spec. 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. An allowlist holds at most 256 entries. none is how you cut a machine off from the internet entirely, since an empty allowlist means unrestricted. It only means something on its own: next to any other entry it adds nothing and is dropped, because the other entries already confine the machine. An internationalized name is kept in its ASCII (punycode) form, which is what the machine looks up: bücher.de becomes xn--bcher-kva.de, under a wildcard too. A name that isn’t a valid internationalized domain name is refused. 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. DNS follows the allowlist too. The machine’s resolver answers only the names the machine may reach: the hosts and wildcards on the list, and the hosts of its host-bound secrets. A lookup of any other name is answered REFUSED without leaving boxd, so a lookup can’t carry data out in the name itself. DNS to any other resolver is blocked like any other destination. 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, and none means nothing is reachable. 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.

From birth, with a machine spec

A machine spec can carry the allowlist, so the machine has it from its first boot and never runs unrestricted:
The same rules apply, and a spec’s entries can’t be empty: leave egress out for no allowlist, or use .egress("none") for a machine that reaches nothing. Change the list later as usual, or with updateSpec. The machine’s spec follows either way. A snapshot keeps its machine’s spec, so a machine created from a snapshot of this one gets the allowlist too, where a snapshot of a machine without a spec gives none.

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.