# 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. `internet` is false whenever something is listed.

- **`deny` without 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; `failed` lists any that could not be reached.

- With **`enforce: true`** the 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 with `403 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_conflict` and the ids, before anything changes.

- `{"default": null}` removes the organization's policy. Setting it needs an `admin` key; changes are in the audit log as `org.egress_update`, and a sandbox's as `sandbox.egress_update` or `sandbox.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.

---
Source: https://docs.kosa8.com/guides/cloud-egress/
