Egress and destinations¶
An agent reaches the outside world only through the credential gateway. What it may reach is its egress; the places it can name are destinations.
Destinations¶
A destination is a named place: a host, the methods and paths allowed, a header allow-list and, optionally, a secret to inject.
| Field | Meaning |
|---|---|
name |
What egress lists. |
host, methods, paths |
Where requests may go. |
header_allowlist |
Which request headers the agent may send. |
inject_secret |
secret:<name>: the gateway adds that credential to requests to this host, and only to this host. |
dev_only |
Required for a loopback or private host. |
llm, mcp and otel are always included in every agent's egress. Destinations are read by every role
(GET /destinations) and written by admins; deleting one is refused with 409 while something uses it.
Egress¶
An agent version's egress is {mode, destinations, upstream_deny_cidrs}:
allowlist: only the named destinations (plus the three platform ones).allow_all: any public host is reachable through the gateway. The deny CIDRs still apply, named destinations' credentials are still injected only on their own hosts, no secret is ever in the sandbox, andCONNECTto any port is allowed. Set it only knowingly.
A team can replace the egress of one role (PUT /teams/{name}/roles/{role}/egress, admin, If-Match);
DELETE returns the role to its agent's egress. Change an agent's own egress with a new
version.
Secrets¶
PUT /secrets/{name} stores a value in OpenBao once; it is never returned. A destination, an integration or an
MCP server refers to it as secret:<name>. A secret value is never printed, logged or repeated, including by
an agent managing Kapelle for a person.
Where it is enforced¶
Firecracker enforces egress at the network: the sandbox can reach only its own gateway instance, DNS is answered by the gateway for allowed hosts only, and the metadata address and private ranges are dropped. On Nevia the egress mode governs traffic through the gateway only; the computer's own network stays open. The gateway itself is described next.
The credential gateway¶
Agent sandboxes hold no outbound credentials. A credential gateway on each sandbox host, outside every sandbox, is the only place a sandbox can send traffic. For each request it works out which agent sent it, checks that agent's policy, adds the right credential and forwards it. Long-lived secrets stay in OpenBao; the gateway holds only short-lived tokens.
| Destination | The sandbox uses | The gateway adds |
|---|---|---|
| Models (LiteLLM) | A base URL on the gateway and a placeholder key | The agent's own LiteLLM virtual key, capped by the team budget |
| Worker MCP tools | A gateway endpoint | A token for the agent |
| GitHub API and git over HTTPS | The gateway as proxy and its CA | An installation token for the team's repositories, valid one hour |
| Package registries | The gateway as proxy | A registry token where one is needed |
| Anything else | The gateway as proxy | Nothing: refused unless the agent's egress allows it |
- One instance per agent. The agent is identified by its network interface, not by anything it sends.
- Policy is generated from the Console's records (an agent's egress, replaced by a team's per-role override); the service falls back to role files only for a role the Console does not know, and a later start serves the last good policy. A controller that cannot be reached at an agent's first start fails that start.
- Audit. Every request is logged as structured OpenTelemetry records with host, method, path, action, status code and duration, plus the agent, team and task, so a request can be traced to who made it.
- MCP servers use the same path: the sandbox sends a placeholder and the gateway injects the secret (MCP servers).
The service is credgwd (credgw/); its dev setup is in the dev environment and host
provisioning in deployment.
Depth: architecture, Credentials.