Documentation/docs/credential/egress-auth

#Egress Auth

Egress auth rules tell Sandbox0 when to apply outbound authentication for matching traffic.

This configuration is carried on the network surface as network.egress.credentialRules, but conceptually it belongs to the credential system:

credentialBindings define what auth material exists.
credentialRules define where and when that material is used.
trafficRules still decide whether the traffic itself is allowed.

Bindings are configured under the same network object everywhere:

template spec.network
sandbox claim config.network
runtime update PUT /api/v1/sandboxes/{id}/network

Binding Fields#

Field	Required	Description
`ref`	Yes	Stable local name matched by `credentialRules[*].credentialRef`
`sourceRef`	Yes	Region-scoped credential source reference to resolve
`projection`	Yes	How the source is shaped for runtime injection
`cachePolicy.ttl`	No	Optional cache lifetime duration string such as `5m` or `1h` for resolved material

Binding Example#

This binding projects a stored token into an Authorization header:

yaml
credentialBindings:
    - ref: gh-token
      sourceRef: github-source
      projection:
          type: http_headers
          httpHeaders:
              headers:
                  - name: Authorization
                    valueTemplate: "Bearer {{token}}"

In this example, {{token}} refers to the token key inside a static_headers source's values map. If the referenced key is missing, header rendering fails.

Rule Fields#

Field	Required	Description
`credentialRef`	Yes	Binding reference to resolve
`protocol`	No	Supported values: `http`, `https`, `grpc`, `tls`, `socks5`, `mqtt`, `redis`
`domains`	No	Domain match list
`ports`	No	Port/protocol constraints
`tlsMode`	No	`passthrough` or `terminate-reoriginate`
`failurePolicy`	No	`fail-closed` or `fail-open`
`rollout`	No	`enabled` or `disabled`

HTTPS Trust Material#

When a credential rule uses TLS interception such as protocol: https, protocol: grpc, or protocol: tls with tlsMode: terminate-reoriginate, Sandbox0 provides the netd MITM CA to sandbox containers as read-only trust material:

File: /var/run/sandbox0/netd/mitm-ca.crt
Env: SANDBOX0_NETD_MITM_CA_FILE=/var/run/sandbox0/netd/mitm-ca.crt

Sandbox0 does not automatically modify the container trust store. Templates and runtimes must opt in if they need to trust the intercepted certificate chain.

Common examples:

Node.js or Claude Code: NODE_EXTRA_CA_CERTS=$SANDBOX0_NETD_MITM_CA_FILE
Python requests: REQUESTS_CA_BUNDLE=$SANDBOX0_NETD_MITM_CA_FILE
curl: CURL_CA_BUNDLE=$SANDBOX0_NETD_MITM_CA_FILE

Example Policy#

This policy allows access to the GitHub API, binds a token source, and injects an Authorization header for matching HTTPS requests:

yaml
mode: block-all
egress:
    trafficRules:
        - name: allow-github-api
          action: allow
          domains:
              - api.github.com
          ports:
              - port: 443
                protocol: tcp
    credentialRules:
        - name: github-auth
          credentialRef: gh-token
          protocol: https
          domains:
              - api.github.com
          ports:
              - port: 443
                protocol: tcp
credentialBindings:
    - ref: gh-token
      sourceRef: github-source
      projection:
          type: http_headers
          httpHeaders:
              headers:
                  - name: Authorization
                    valueTemplate: "Bearer {{token}}"

Here, {{token}} is rendered from the token entry stored in the bound static_headers source. Keep the projection template keys aligned with the source contents.

Update Runtime Policy#

PUT/api/v1/sandboxes/{id}/network

go
_, err = sandbox.UpdateNetworkPolicy(ctx, apispec.SandboxNetworkPolicy{
  Mode: apispec.SandboxNetworkPolicyModeBlockAll,
  Egress: apispec.NewOptNetworkEgressPolicy(apispec.NetworkEgressPolicy{
      TrafficRules: []apispec.TrafficRule{
          {
              Name: apispec.NewOptString("allow-github-api"),
              Action: apispec.TrafficRuleActionAllow,
              Domains: []string{"api.github.com"},
              Ports: []apispec.PortSpec{
                  {
                      Port: 443,
                      Protocol: apispec.NewOptString("tcp"),
                  },
              },
          },
      },
      CredentialRules: []apispec.EgressCredentialRule{
          {
              Name: apispec.NewOptString("github-auth"),
              CredentialRef: "gh-token",
              Protocol: apispec.NewOptEgressAuthProtocol(apispec.EgressAuthProtocolHTTPS),
              Domains: []string{"api.github.com"},
              Ports: []apispec.PortSpec{
                  {
                      Port: 443,
                      Protocol: apispec.NewOptString("tcp"),
                  },
              },
              FailurePolicy: apispec.NewOptEgressAuthFailurePolicy(apispec.EgressAuthFailurePolicyFailClosed),
          },
      },
  }),
  CredentialBindings: []apispec.CredentialBinding{
      {
          Ref: "gh-token",
          SourceRef: "github-source",
          Projection: apispec.ProjectionSpec{
              Type: apispec.CredentialProjectionTypeHTTPHeaders,
              HttpHeaders: apispec.NewOptHTTPHeadersProjection(apispec.HTTPHeadersProjection{
                  Headers: []apispec.ProjectedHeader{
                      {
                          Name: "Authorization",
                          ValueTemplate: "Bearer {{token}}",
                      },
                  },
              }),
          },
      },
  },
})
if err != nil {
  log.Fatal(err)
}

ℹ

For supported protocols, auth material is resolved and injected by the egress path. The sandbox process does not need direct access to the raw credential source contents.

Next Steps#

Sandbox Network

Define the traffic allow and deny policy around trafficRules

Template Configuration

Set default egress auth policy at template level with spec.network

Self-Hosted Configuration

Carry the same network and credential policy model into private deployments