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, the ctld network runtime 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.

Egress Proxy

Behavior#

Configure Proxy#

Limits#

Next Steps#

Sandbox Services

Sandbox Functions

Webhooks