Documentation/docs/sandbox/network

#Network

SandboxNetworkPolicy controls outbound traffic for a sandbox.

Use mode as the default fallback, and use egress.trafficRules for explicit ordered allow and deny behavior.

Policy Shape#

Field	Description
`mode`	Default fallback for unmatched traffic: `allow-all` or `block-all`
`egress.trafficRules`	Ordered allow/deny rules. First matching rule wins
`egress.protocolRules`	Protocol-aware operation controls for allowed traffic. See Protocol Controls
`egress.credentialRules`	Destination-scoped outbound auth rules, optionally constrained by HTTP request matchers. See Credential / Egress Auth
`egress.proxy`	Customer-managed SOCKS5 route for allowed TCP traffic. See Egress Proxy
`network.credentialBindings`	Local bindings used by `credentialRules`. See Credential / Egress Auth

The same public SandboxNetworkPolicy shape is used in:

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

Mode And Rule Evaluation#

trafficRules are evaluated in order.
The first matching rule wins.
If no rule matches, traffic falls back to mode.

ℹ

Use trafficRules for new policies. Legacy allowed* and denied* fields still work, but they are deprecated and should not be mixed with trafficRules.

ℹ

If a credential rule uses tlsMode: terminate-reoriginate, Sandbox0 exposes the netd MITM CA as SANDBOX0_NETD_MITM_CA_FILE and configures procd-managed processes with a combined CA bundle through common TLS environment variables.

Traffic Rule Fields#

Field	Required	Description
`action`	Yes	`allow` or `deny`
`name`	No	Stable identifier for replacement and merge
`domains`	No	Domain match list
`cidrs`	No	CIDR match list
`ports`	No	Port/protocol constraints
`appProtocols`	No	Classified application protocols such as `http`, `tls`, `ssh`, `dns`, `redis`

HTTP Request Matchers#

credentialRules[*].httpMatch narrows credential injection for HTTP-family rules after the HTTP request is visible to netd. It can match methods, exact paths, path prefixes, query parameters, and headers.

For HTTPS and gRPC rules, request matching requires tlsMode: terminate-reoriginate so netd can read the request before injecting credentials.

Protocol Rules#

protocolRules run after traffic is allowed. The first supported protocol is MCP over HTTP/HTTPS. Use it to allow a sandbox to reach an MCP server while limiting tool calls by tool name.

For HTTPS MCP servers, set tlsMode: terminate-reoriginate on the protocol rule so netd can inspect JSON-RPC request bodies.

Get Network Policy#

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

go
policy, err := sandbox.GetNetworkPolicy(ctx)
if err != nil {
  log.Fatal(err)
}
fmt.Printf("mode=%s\n", policy.Mode)

Update Network Policy#

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

Allow Only GitHub HTTPS#

go
_, err = sandbox.UpdateNetworkPolicy(ctx, apispec.SandboxNetworkPolicy{
  Mode: apispec.SandboxNetworkPolicyModeBlockAll,
  Egress: apispec.NewOptNetworkEgressPolicy(apispec.NetworkEgressPolicy{
      TrafficRules: []apispec.TrafficRule{
          {
              Name: apispec.NewOptString("allow-github"),
              Action: apispec.TrafficRuleActionAllow,
              Domains: []string{"github.com", "api.github.com"},
              Ports: []apispec.PortSpec{
                  {
                      Port: 443,
                      Protocol: apispec.NewOptString("tcp"),
                  },
              },
          },
      },
  }),
})
if err != nil {
  log.Fatal(err)
}

Legacy Compatibility#

egress.allowedDomains, allowedCidrs, allowedPorts, deniedDomains, deniedCidrs, and deniedPorts are still accepted for compatibility:

In block-all, only allowed* fields are enforced.
In allow-all, only denied* fields are enforced.

Prefer trafficRules for all new policies.

Next Steps#

Protocol Controls

Restrict MCP tools and future protocol-level operations.

Egress Proxy

Route allowed TCP egress through a customer-managed SOCKS5 proxy.

Sandbox Services

Expose named sandbox ports through public HTTP service routes.