Documentation/docs/sandbox/proxy

#Egress Proxy

Sandbox egress proxy routes allowed outbound TCP traffic through a customer-managed SOCKS5 proxy.

Use it when a sandbox needs a customer-controlled egress IP, customer-side audit, or access to services reachable from the proxy network.

Behavior#

  • Only TCP traffic is supported.
  • Sandbox network policy is still enforced before the proxy connection is opened.
  • Platform deny rules still apply.
  • Proxy credentials are referenced through credential bindings and are not stored in pod annotations.
  • UDP, QUIC, HTTP proxy, and VPN tunnels are not part of this feature.
ℹ

For domain-classified TCP traffic, netd sends the hostname to the SOCKS5 proxy so the proxy can resolve it from the customer network side. The sandbox process still needs to open a TCP connection first, so make sure the application can resolve or otherwise reach the initial destination address.

Configure Proxy#

PUT

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

Create a credential source for proxies that require username/password auth, then attach the proxy to the sandbox network policy.

go
source, err := client.CreateCredentialSource(ctx, apispec.CredentialSourceWriteRequest{
  Name: "corp-proxy-source",
  ResolverKind: apispec.CredentialSourceResolverKindStaticUsernamePassword,
  Spec: apispec.CredentialSourceWriteSpec{
      StaticUsernamePassword: apispec.NewOptStaticUsernamePasswordSourceSpec(
          apispec.StaticUsernamePasswordSourceSpec{
              Username: os.Getenv("SOCKS5_USERNAME"),
              Password: os.Getenv("SOCKS5_PASSWORD"),
          },
      ),
  },
})
if err != nil {
  log.Fatal(err)
}

credentialRef := "corp-proxy"
_, err = sandbox.UpdateNetworkPolicy(ctx, apispec.SandboxNetworkPolicy{
  Mode: apispec.SandboxNetworkPolicyModeBlockAll,
  Egress: apispec.NewOptNetworkEgressPolicy(apispec.NetworkEgressPolicy{
      TrafficRules: []apispec.TrafficRule{
          {
              Name: apispec.NewOptString("allow-private-api"),
              Action: apispec.TrafficRuleActionAllow,
              Domains: []string{"api.internal.example.com"},
              Ports: []apispec.PortSpec{
                  {
                      Port: 443,
                      Protocol: apispec.NewOptString("tcp"),
                  },
              },
              AppProtocols: []apispec.TrafficRuleAppProtocol{
                  apispec.TrafficRuleAppProtocolTLS,
              },
          },
      },
      Proxy: apispec.NewOptEgressProxyPolicy(apispec.EgressProxyPolicy{
          Type: apispec.EgressProxyTypeSocks5,
          Address: "proxy.example.com:1080",
          CredentialRef: apispec.NewOptString(credentialRef),
      }),
  }),
  CredentialBindings: []apispec.CredentialBinding{
      {
          Ref: credentialRef,
          SourceRef: source.Name,
          Projection: apispec.ProjectionSpec{
              Type: apispec.CredentialProjectionTypeUsernamePassword,
              UsernamePassword: &apispec.UsernamePasswordProjection{},
          },
      },
  },
})
if err != nil {
  log.Fatal(err)
}

credentialRef is optional. Leave it empty for a SOCKS5 proxy that does not require authentication. In the CLI, omit --proxy-credential-ref and --proxy-credential-source for unauthenticated proxies.

Limits#

Egress proxy is a TCP routing feature. It does not proxy DNS datagrams, UDP application protocols, or QUIC. If a workload uses HTTP/3 or QUIC, configure the client to use TCP/TLS instead.

Next Steps#

Sandbox Services

Expose named sandbox ports through public HTTP service routes.

Webhooks

Receive signed sandbox lifecycle, service, and file-related events.