Skip to documentation
API + guides

01Documentation

Egress Proxy

Sandbox egress proxy routes supported outbound TCP paths through a customer-managed SOCKS5 proxy. Check the adapter limitations below before depending on it for a fixed egress route.

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 runtime allocation metadata or exposed to the sandbox process.
  • UDP, QUIC, HTTP proxy endpoints, and VPN tunnels are not part of this feature. Configuring a SOCKS5 proxy does not disable non-TCP traffic that the network policy otherwise allows.
ℹ

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.

Adapter Compatibility#

The shared TCP relay and TLS/HTTPS upstream paths use the configured SOCKS5 proxy. Two current adapter combinations open direct upstream connections:

  • plain HTTP inspection for HTTP/MCP protocol controls or credential injection;
  • SSH credential injection through the ssh_proxy adapter.

These combinations do not provide a guaranteed SOCKS5 egress route. The example below limits tenant traffic to classified TLS on TCP port 443. Platform policy and template rule merging still apply, as described in Network.

The proxy endpoint must be reachable from the platform's network runtime, rather than only from the sandbox. Loopback, link-local, cloud metadata, multicast and platform-denied endpoint addresses are rejected.

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#