Egress Policy API: Manage Sandbox Outbound Network Rules

The egress sidecar is a per-sandbox process that enforces outbound network policy using DNS-based filtering. It runs inside the sandbox pod and is accessible at port 18080 on the sidecar’s local address. From the server side, access is established by first resolving the sandbox endpoint for the egress port via GET /v1/sandboxes/{sandboxId}/endpoints/{port}, then calling the sidecar endpoint directly. This API supports runtime inspection and mutation of FQDN-based egress rules, as well as management of sandbox-local Credential Vault bindings for transparent credential injection.

Initial egress policy configuration (set at sandbox creation time) is part of the networkPolicy field in POST /v1/sandboxes. This API is for runtime inspection and mutation after the sandbox is already running.

The egress sidecar does not require an auth header by default. However, when a sandbox is created with secureAccess: true, the endpoint resolver returns required headers — these must be forwarded on every egress API request.

GET /policy

Returns the currently enforced egress policy and the sidecar’s derived runtime mode metadata.

Response — 200 OK

status

string

Operation status reported by the sidecar. Example: "ok".

mode

string

Derived runtime mode for the current policy. Example: "deny_all".

enforcementMode

string

Egress sidecar enforcement backend mode. Example: "dns".

reason

string

Optional human-readable reason when the sidecar returns extra context.

policy

object

The currently enforced network policy.

Show policy fields

policy.defaultAction

string

Default action when no egress rule matches. Enum: allow, deny.

policy.egress

array

Ordered list of egress rules. Each rule has action (allow|deny) and target (FQDN or wildcard domain).

Example

curl http://localhost:18080/policy

{
  "status": "ok",
  "mode": "deny_all",
  "enforcementMode": "dns",
  "policy": {
    "defaultAction": "deny",
    "egress": [
      { "action": "allow", "target": "pypi.org" }
    ]
  }
}

PATCH /policy

Merges incoming egress rules into the currently enforced policy. This uses merge semantics: existing rules remain unless overridden, incoming rules take higher priority than existing rules, and if multiple incoming rules reference the same target, the first one wins.

Request Body

An array of NetworkRule objects (minimum 1 item):

[].action

string

required

Whether to allow or deny the target. Enum: allow, deny.

[].target

string

required

FQDN or wildcard domain to match. Examples: "example.com", "*.example.com". IP/CIDR targets are not currently supported.

Response — 200 OK

Returns a PolicyStatusResponse with the updated status, mode, and enforcementMode.

Patch Semantics

First Rule Wins
Merge With Existing

When multiple incoming rules reference the same target, only the first rule in the array is applied:

[
  { "action": "allow", "target": "example.com" },
  { "action": "deny",  "target": "example.com" }
]

Result: example.com is allowed (first rule wins).

Existing rules not referenced by the patch remain unchanged. Incoming rules for new targets are appended with higher priority:

[
  { "action": "allow", "target": "newdomain.io" }
]

Result: newdomain.io is added to the policy; all previously existing rules are preserved.

Example

curl -X PATCH http://localhost:18080/policy \
  -H "Content-Type: application/json" \
  -d '[
    { "action": "allow", "target": "api.openai.com" },
    { "action": "deny",  "target": "bad.example.com" }
  ]'

DELETE /policy

Removes specific egress rules from the currently enforced policy by target FQDN. Targets not present in the current policy are silently ignored (idempotent operation).

Request Body

An array of target strings (minimum 1 item) identifying the rules to remove:

["bad.example.com", "*.blocked.org"]

Response — 200 OK

Returns a PolicyStatusResponse confirming the updated policy state.

Example

curl -X DELETE http://localhost:18080/policy \
  -H "Content-Type: application/json" \
  -d '["bad.example.com", "*.blocked.org"]'

POST /credential-vault

Creates the initial sandbox-local Credential Vault revision and activates it in Credential Proxy. Inline credential values are write-only and are never returned by this or any other endpoint. Returns 409 Conflict if a Credential Vault already exists.

Request Body

credentials

array

required

Array of credentials to store.

Show credential fields

credentials[].name

string

required

Unique credential name.

credentials[].source

object

required

Inline credential source. Must have type: "inline" and a write-only value string.

bindings

array

required

Array of credential bindings that map credentials to outbound request targets.

Show binding fields

bindings[].name

string

required

Unique binding name.

bindings[].match

object

required

Request match criteria: hosts (array, required), schemes (default [https]), ports (default [443]), methods (default all), paths (default ["/*"]).

bindings[].auth

object

required

Auth injection type. One of: bearer, basic, apiKey, or customHeaders.

Response — 201 Created

revision

integer

required

Current vault revision number.

credentials

array

required

Sanitized credential metadata (names and source types only — no values).

bindings

array

required

Sanitized binding metadata.

Example

curl -X POST http://localhost:18080/credential-vault \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": [
      { "name": "openai-key", "source": { "type": "inline", "value": "sk-..." } }
    ],
    "bindings": [
      {
        "name": "openai-binding",
        "match": { "hosts": ["api.openai.com"] },
        "auth": { "type": "bearer", "credential": "openai-key" }
      }
    ]
  }'

GET /credential-vault

Returns sanitized Credential Vault state. Credential values are never included in responses.

Response — 200 OK

revision

integer

required

Current vault revision number.

credentials

array

required

Array of CredentialMetadata objects (name, sourceType, revision).

bindings

array

required

Array of CredentialBindingMetadata objects (name, revision, match, auth type metadata).

Example

curl http://localhost:18080/credential-vault

PATCH /credential-vault

Atomically mutates credentials and bindings in the vault. Supports add, replace, and delete operations for both credentials and bindings. Optionally enforces optimistic concurrency via expectedRevision.

Request Body

expectedRevision

integer

Optional optimistic concurrency guard. The patch is rejected with 409 Conflict if the vault’s current revision does not match.

credentials

object

Credential mutation set with optional add, replace, and delete arrays.

bindings

object

Binding mutation set with optional add, replace, and delete arrays.

Example

curl -X PATCH http://localhost:18080/credential-vault \
  -H "Content-Type: application/json" \
  -d '{
    "expectedRevision": 1,
    "credentials": {
      "add": [
        { "name": "new-key", "source": { "type": "inline", "value": "abc123" } }
      ],
      "delete": ["old-key"]
    }
  }'

DELETE /credential-vault

Deletes the entire sandbox-local Credential Vault. Returns 204 No Content on success.

Example

curl -X DELETE http://localhost:18080/credential-vault

GET /credential-vault/credentials

Lists sanitized metadata for all credentials in the vault.

Example

curl http://localhost:18080/credential-vault/credentials

GET /credential-vault/credentials/

Returns sanitized metadata for a single credential. Credential values are never returned.

Path Parameters

credential_name

string

required

Credential name to retrieve.

Example

curl http://localhost:18080/credential-vault/credentials/openai-key

GET /credential-vault/bindings

Lists sanitized metadata for all credential bindings.

Example

curl http://localhost:18080/credential-vault/bindings

GET /credential-vault/bindings/

Returns sanitized metadata for a single credential binding.

Path Parameters

binding_name

string

required

Binding name to retrieve.

Example

curl http://localhost:18080/credential-vault/bindings/openai-binding

Auth Injection Types

The auth field in a credential binding supports four injection strategies:

Type	Description
`bearer`	Injects `Authorization: Bearer <value>` header using the referenced credential.
`basic`	Injects `Authorization: Basic <base64(user:pass)>` using a pre-encoded credential.
`apiKey`	Injects a named request header (e.g. `X-Api-Key`) with the credential value.
`customHeaders`	Injects one or more named headers, each mapped to a credential value.

Overview

Lifecycle API

Execution API

Egress & Diagnostics

Documentation Index

​GET /policy

​Response — 200 OK

​Example

​PATCH /policy

​Request Body

​Response — 200 OK

​Patch Semantics

​Example

​DELETE /policy

​Request Body

​Response — 200 OK

​Example

​POST /credential-vault

​Request Body

​Response — 201 Created

​Example

​GET /credential-vault

​Response — 200 OK

​Example

​PATCH /credential-vault

​Request Body

​Example

​DELETE /credential-vault

​Example

​GET /credential-vault/credentials

​Example

​GET /credential-vault/credentials/

​Path Parameters

​Example

​GET /credential-vault/bindings

​Example

​GET /credential-vault/bindings/

​Path Parameters

​Example

​Auth Injection Types

Build docs developers (and LLMs) love

GET /policy

Response — 200 OK

Example

PATCH /policy

Request Body

Response — 200 OK

Patch Semantics

Example

DELETE /policy

Request Body

Response — 200 OK

Example

POST /credential-vault

Request Body

Response — 201 Created

Example

GET /credential-vault

Response — 200 OK

Example

PATCH /credential-vault

Request Body

Example

DELETE /credential-vault

Example

GET /credential-vault/credentials

Example

GET /credential-vault/credentials/

Path Parameters

Example

GET /credential-vault/bindings

Example

GET /credential-vault/bindings/

Path Parameters

Example

Auth Injection Types