kosa8 docs

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
}

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":[]}

What is enforced, exactly