Guides / kosa8 Cloud / Egress controls
Egress controls
Every packet a kosa8 Cloud sandbox sends leaves through a userspace network on the host, outside the sandbox's VM. An egress policy tells that network what to let out. Nothing inside the sandbox can change it, and you can change it while the sandbox runs.
A policy
{
"internet": false, // nothing leaves but what allow and presets name
"allow": ["api.openai.com", "*.github.com", "10.20.0.0/16"],
"presets": ["npm", "pypi"], // registry host sets: GET /v1/egress/presets
"deny": ["gist.github.com"] // refused even where allow covers it
}
- Nothing set (or
{"internet": true}): the sandbox reaches the internet. This is the default. {"internet": false}alone: nothing leaves at all.- An allow list or presets: only those hosts.
internetis false whenever something is listed. denywithout an allow list: everything but those.
Entries are hostnames (exact), *.domain wildcards (any name below the domain, not the
domain itself), IPv4 addresses or IPv4 CIDRs. A policy has at most 256 entries, presets aside.
Presets: npm, pypi, github, go, crates,
rubygems, maven, apt, alpine, docker,
huggingface, ai (the main model APIs), and common (every
package-registry preset together).
Set it when you create a sandbox
curl -s -X POST https://api.kosa8.com/v1/sandboxes \
-H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
-d '{"egress":{"presets":["common"],"allow":["api.anthropic.com"]}}'
# {"sandbox":{"id":"sbx_…", …, "egress":{"internet":false,"allow":["api.anthropic.com"],
# "presets":["common"],"deny":[],"source":"sandbox","enforced":"allow:api.anthropic.com,registry.npmjs.org,…"}}}
The policy is in force before the create answers. If the host cannot apply it, the sandbox is deleted and the create fails, so you never hold the id of a sandbox that is more open than you asked.
Change it while the sandbox runs
curl -s -X PUT https://api.kosa8.com/v1/sandboxes/sbx_…/egress \
-H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
-d '{"internet":false}'
# {"egress":{…,"enforced":"deny"},"applied":true,"sleeping":false}
The new policy applies from the next packet, so an open connection it refuses stops there. A
sleeping sandbox takes it when it wakes, and a sandbox keeps its policy across sleep, wake and
rewind. GET …/egress shows the policy in force and where it came from
(sandbox, org or default); DELETE …/egress goes back to the
organization's default.
For the whole organization
curl -s -X PUT https://api.kosa8.com/v1/org/egress \
-H "Authorization: Bearer $KOSA8_ADMIN_KEY" -H 'Content-Type: application/json' \
-d '{"default":{"presets":["common"],"deny":["pastebin.com"]},"enforce":true}'
# {"egress":{"default":{…},"enforce":true,"enforced":"allow:…;deny:pastebin.com"},"applied":12,"failed":[]}
- The default applies to every sandbox that does not set its own, new and
existing. Running and sleeping sandboxes (up to 500) get it at once;
failedlists any that could not be reached. - With
enforce: truethe default is also a ceiling. A sandbox may only narrow it: an allow list inside the organization's, or no internet. Anything else is refused with403 egress_not_allowed, and the organization's deny list is added to every sandbox's. - An enforced policy that an existing sandbox's own policy does not fit inside is refused with
409 egress_conflictand the ids, before anything changes. {"default": null}removes the organization's policy. Setting it needs anadminkey; changes are in the audit log asorg.egress_update, and a sandbox's assandbox.egress_updateorsandbox.egress_reset.
What is enforced, exactly
- An allow list is the boundary. The host answers the sandbox's DNS itself and lets packets through only to addresses that an allowed name resolved to, or that an allowed CIDR covers. A program that connects to an address it already knows gets nowhere.
- A deny by CIDR is refused for every packet.
- A deny by name is refused at DNS. A program that already knows the name's address can still reach it unless an allow list or a CIDR deny covers that address. Use an allow list when it matters.