Egress: watch it, then close it

$ bin/egress-proxy summary --days 14
# tick the hosts your team needs to build the allowlist line

What it is

Egress control is three pieces on your host working together. An iptables chain sends each organisation's network to one forward proxy and drops everything else. The proxy decides by hostname against an allowlist. A DNS filter on each organisation's gateway answers only allowlisted names. In observe the proxy records what it would refuse and lets it through. In deny it refuses.

On your host only. A workspace on a member's own computer, where an operator has granted it and the organisation has turned it on, uses that computer's own network. There, internet access is observed, not enforced: the platform sees only the calls that go through its brokers (git, AI and the portal). DNS filtering is not enforced there either.

How it works

1. Network. Each organisation's workspaces sit on their own Docker network, agentstack-t-<org>. Creating a workspace is refused unless the firewall covers that network and a DNS gateway exists.
2. Firewall. In DOCKER-USER, each organisation subnet jumps to one owned chain, AGENTSTACK_EGRESS. It returns traffic bound for the proxy, DNS and the host brokers, then LOGs (prefix agentstack-egress-deny, rate-limited) and DROPs everything else. A boot unit restores it after a reboot.
3. DNS filter. A hardened dnsmasq on each organisation's gateway forwards allowlisted names and answers REFUSED to the rest. Refusals are written to the egress audit stream. No filter means no DNS, so it fails closed too.
4. Proxy. Workspaces reach the internet through egress-proxy with a per-workspace proxy credential, so every record names a workspace. It computes a decision on every connection, whatever the mode, and reads egress_enforce on every connection: a flip to deny, or back, needs no restart.
5. Two conditions to block. A connection is refused only when the security profile puts egress on an allowlist (metered, guarded or strict) and enforcement is deny. Under the open profile, deny blocks nothing.
6. Always on. Below file transfer both, in every mode: github.com and *.github.com are refused (GitHub goes through the git broker; codeload.github.com source archives still work), upload.pypi.org is refused, and copy-tool ports 22, 2222, 873, 20, 21, 989, 990 and 69 are refused before connecting, and on any other port the proxy recognises ssh, rsync and ftp by their opening bytes and refuses before any of the copy is relayed.

Hostnames, not packets. Under observe, a bare IP or a hostname that resolves to GitHub is only logged. Under deny, a bare IP matches no allowlist entry and is refused.

Defaults

Configure it

Everything is set with bin/policy on the host or in the console. The proxy reads policy on every connection, so none of these needs a restart.

On the host

# where you stand: mode, profile and what is enforced
$ bin/egress-proxy status
$ bin/egress-proxy posture --tenant acme
# would this host be allowed for acme? decides nothing, changes nothing
$ bin/egress-proxy check --host registry.example.org --tenant acme
# what the organisation reached, ranked, with a proposed list
$ bin/egress-proxy summary --days 14
$ bin/egress-proxy summary --days 14 --workspace acme/dev01 --json
# add hosts for one organisation (added to the platform list)
$ bin/policy set --scope tenant --target acme --key egress_allowlist --value 'registry.example.org,.example.net'
# promote one organisation to deny, or the whole host
$ bin/policy set --scope tenant --target acme --key egress_enforce --value deny
$ bin/policy set --key egress_enforce --value deny
# what acme actually sees after both scopes are applied
$ bin/policy get-for --tenant acme --key egress_enforce

A platform set replaces the whole list. bin/policy set --key egress_allowlist without a scope writes the platform list as given, dropping anything you leave out. Start from the proposed line summary prints, which includes the current entries.

In the console

Organisation

OrganisationsacmeSettingsEgress

Mode and the organisation's added hosts.

Requests

OrganisationsacmeSettingsAllowlist requests

Approve or deny what members asked for, with a reason recorded on the audit trail.

Operator

ConsoleEgress policy

and

ConsoleEgress monitor

for the platform list and traffic across organisations.

Developer

WorkspaceLogsegress

Each refused or observed row has a request button that asks an administrator to allow that host.

Firewall and DNS filter

$ sudo bin/egress-firewall preflight
$ sudo bin/egress-firewall up
$ sudo bin/egress-firewall verify
$ sudo bin/egress-firewall persistence
$ bin/dns-filter status
$ bin/dns-filter sync
$ bin/egress-coverage

Tasks

Promote an organisation from observe to deny

1. Let the team work for a week in observe

   Nothing to set: it is the default. Optionally require identity so every record names a workspace.

   on the hostCopy

   $ bin/policy set --key egress_identity --value required

   Expected: connections without a workspace credential get a 407 that says the workspace must present its proxy credential.

2. Read what they reached

   on the hostCopy

   $ bin/egress-proxy summary --days 14

   Expected: a ranked table (host, requests, workspaces, bytes up and down, would-deny count, verdict) with verdicts ALREADY ALLOWED, ALLOW or NEEDS A DECISION, then a proposed allowlist line. Nothing is applied automatically.

3. Add the hosts that are legitimate

   on the hostCopy

   $ bin/policy set --scope tenant --target acme \
       --key egress_allowlist --value 'registry.example.org,cdn.example.net'

   Expected: bin/egress-proxy check --host registry.example.org --tenant acme now prints allowlist ALLOW.

4. Switch the organisation to deny

   on the hostCopy

   $ bin/policy set --scope tenant --target acme --key egress_enforce --value deny

   Expected: the next connection to an unlisted host gets a 403 whose body starts egress-proxy: paste.example.io:443 is not permitted from this workspace. To back out during an incident, set it to observe; it applies on the next connection.

5. Handle the first request

   A developer who hits a new host presses request in the Logs pane. You approve it in Allowlist requests; approving adds the host to the organisation's list and writes allowlist-approve to the egress stream.

Let one organisation use a private registry

1. Check what would happen now

   on the hostCopy

   $ bin/egress-proxy check --host registry.example.org --port 443 --tenant acme

   Expected: allowlist DENY with the reason registry.example.org is not on the allowlist, and a result of OBSERVE or DENY depending on the mode.

2. Add it for acme only

   Use the organisation scope, so other organisations on the host are unaffected. If the registry is not on 443 or 80, an operator must add the port to egress_ports for the whole host.

3. Confirm DNS resolves it

   Allowlisted names are forwarded by the organisation's DNS filter. Run bin/dns-filter sync if the filter has not picked up the change, then bin/dns-filter status.

Prove every organisation network is covered

1. Run the coverage check

   on the hostCopy

   $ bin/egress-coverage
   $ bin/egress-coverage --json

   Expected: exit 0 with every organisation network closed. Exit 1 means gaps or a failed verify; exit 2 means it could not tell.

2. Close a gap

   on the host, as rootCopy

   $ sudo bin/egress-firewall up
   $ sudo bin/egress-firewall verify

   Expected: verify passes with no line naming an uncovered subnet.

Verify it works

Good looks like: check says ALLOW for what the team needs and DENY (exit 2) for an unknown host; bin/egress-coverage exits 0; bin/egress-firewall verify passes; the egress audit stream shows deny records for refused hosts and allow for the rest. /api/readyz also reports firewall and DNS-filter coverage beside its checks (see Operate).

Troubleshooting

Limits and what is not built yet

• Observe by default. Deny by default for fresh installs is built and held back while the team runs on deny first.
• npm publish can upload code to an allowed registry, in any mode.
• Some AI provider APIs are reachable directly through the allowlist.
• Copy tools. Below file transfer both, on workspaces on your host, in both egress modes: copy-tool ports (22, 2222, 873, 20, 21, 989, 990, 69) are refused before connecting, and on any other port the egress proxy recognises ssh, rsync and ftp by their opening bytes and refuses before any of the copy is relayed; the firewall drops anything that bypasses the proxy. Not covered: members' own computers (egress there is observed, not enforced); a copy tool hidden inside an ordinary HTTPS connection to an allowed site, and HTTPS uploads to an allowed site, which are egress-allowlist questions; and a workspace under privileged full Docker, where the firewall guarantee no longer holds.
• Detectable, not preventable: preview links, and code shown in an attached editor or terminal. The file-transfer setting does govern the console's Files pane, the browser IDE's Download and Upload, and scp, sftp and rsync over desktop IDE attach; an attach-copy refusal is logged inside the workspace only, not on the platform audit trail.
• No payload inspection or DLP, and no TLS termination.
• No per-organisation destination feed in the organisation console yet; operators see traffic in Egress monitor and summary.
• No coverage on hosts where the firewall's root copy is not installed.
• Members' computers. If a platform operator grants it and your organisation turns it on, a member's own computer can host their workspaces. There, internet access is observed, not enforced; DNS filtering is not enforced; the source on its disk is readable by whoever uses it; and Docker is not available.
• Docker containers in a workspace get no internet by default; with docker_egress at proxy they use the workspace's own allowlist. Pulled images are one shared cache on the host, so a workspace can tell an image was already pulled.

Related

Verified against the main branch, 4 Oct 2026.