Restrict network egress

By default an agent can reach the platform’s own services and nothing else. To let it call an external API, declare the host in the manifest. The declaration is part of the version’s contract: validated at deploy, frozen for the version, and enforced on every connection at run time.

agent.yaml

network:
  egress:
    - github.com
    - api.example.com

Availability: Author-declared egress is enabled per tenant; without it the list is validated and recorded but no external route exists. See What is available where.

At a glance

• Entries are bare hostnames. An entry covers its subdomains.
• An administrator’s per-tenant ceiling only narrows your list; it never adds to it.
• A declaration outside the ceiling fails the deploy in seconds, naming the entry and the ceiling.
• Platform destinations, such as the LLM gateway, are added for you and are not declarable.

Allow arbitrary public websites

For an agent that needs to browse websites it cannot enumerate in advance, use:

agent.yaml

network:
  egress_mode: public

Omit egress, or leave it empty. A non-empty hostname list combined with public is rejected. Without egress_mode, the existing hostname-list behavior applies; allowlist can also be explicit.

An unset tenant ceiling permits public mode. Any configured hostname ceiling, including an empty one, rejects it at deploy and session admission. Public-mode cog agent deploy --dry-run performs an authenticated read-only ceiling validation; it creates no build and uploads no source.

Public means any canonical public hostname through the managed proxy. Private, metadata, reserved and platform infrastructure addresses remain blocked, including when public DNS points to them. It does not enable raw IP destinations, direct sockets, UDP or QUIC. Clients must use the proxy; transport and port limits still apply. Platform credentials and other policy controls remain unchanged.

Availability: Public mode requires runtime-api, cr-node and cr-helper versions supporting the versioned egress policy, plus an enabled external route and trusted resolver. An older receiver refuses activation. Deploy the supporting platform release before deploying a public-mode agent.

The declaration is immutable per agent version. Ceiling tightening blocks new sessions and resumes; it does not close an active connection. Stop affected sessions for immediate revocation, then start new sessions under the updated ceiling. Session responses expose external_egress_policy, and connection ledger records identify the mode and ceiling revision in their policy ID.

Write a valid entry

Each entry is a lowercase hostname with at least two labels, no scheme, port, path, or trailing dot. Anything else is refused at deploy rather than rewritten, so what you wrote is what is enforced.

Not allowed	Why
*.github.com	No wildcards. github.com already covers api.github.com.
https://github.com, github.com:443, github.com/path	The match is on host alone.
140.82.121.4	An address has no DNS identity; the allowlist matches the host the agent asks for.
loopback or in-cluster names	Names for the sandbox itself or the platform’s own network are never declarable.
GitHub.com, github.com.	Not canonical. Write github.com.

Declare the narrowest name that covers what you need. github.com admits api.github.com; it does not admit notgithub.com.

The tenant ceiling

Your administrator can set a ceiling for the tenant. Your declaration is intersected with it:

• A ceiling of github.com admits a declaration of api.github.com, because that is narrower.
• A declaration of example.com under a ceiling that does not include it fails the deploy with the entry and the ceiling named, before any build is created.
• An unconfigured tenant admits any public hostname, so an unset ceiling behaves as though only your manifest applied.

What is enforced, and where

• At deploy: the grammar and the tenant ceiling, before a build exists.
• At run time: the managed proxy admits the platform’s destinations plus your declared hosts, or public hostnames when egress_mode: public is selected. Every external destination must resolve to a checked public address. A refused connection fails at the agent with the host named.

Change the list

The list is immutable for a version. To add or remove a host, change the manifest and deploy a new version, then roll it out. See Deploy a version.

Where to go next

• Policy, approvals, and evidence: how egress fits with the other ceilings.
• Agent manifest: the field reference.