Skip to main content
A self-hosted sandbox-host can send every outbound connection from Sandboxes through your corporate forward proxy instead of dialing destinations directly. Use this when your network allows outbound traffic only through a proxy, or when your security team needs all Sandbox traffic to pass a proxy’s access policy and logging. For how Sandbox traffic leaves a microVM, see Sandbox architecture. For installation, see Enable Sandboxes.

​
Understand how proxied egress works

Each outbound TCP connection from a Sandbox reaches the Sandbox auth proxy on its host first. The host applies the Sandbox’s allow and deny lists and auth proxy rules, then sends the traffic to your forward proxy the way a client configured with HTTP_PROXY and HTTPS_PROXY does:
  • Plain HTTP: Sent as standard proxy requests, such as GET http://example.com/path. HTTP to an allow-listed IP address is the exception: it goes through a CONNECT tunnel to port 80, so the host checks the address the Sandbox connected to rather than its Host header.
  • HTTPS and other TCP: Sent through CONNECT tunnels to the destination host and port, such as CONNECT example.com:443 or CONNECT github.com:22.
The host also applies these rules:
  • No direct fallback: When the forward proxy rejects a request or cannot open a tunnel, the request or connection fails. The host never retries it directly.
  • Bypass list: The host dials destinations in noProxy directly, with the same Sandbox access checks.
  • LangSmith API: The host dials HTTPS requests from a Sandbox to your LangSmith installation’s API directly, not through the forward proxy.
Proxying happens on the host, outside the Sandbox. Code inside a Sandbox does not see the forward proxy address and does not need HTTP_PROXY or HTTPS_PROXY set.

​
Check the requirements

Proxied egress requires:
  • LangSmith 0.17.32 or later on the 0.17 release line, or 0.18.5rc1 or later on the 0.18 line, for the sandbox-host image.
  • LangSmith Helm chart 0.17.7 or later on the 0.17 release line, or 0.18.0-rc.19 or later on the 0.18 line, for sandboxes.authProxy.httpProxy.
  • A forward proxy that accepts standard HTTP proxy requests and CONNECT to port 443. To reach other TCP services, such as Git over SSH on port 22, or HTTP on an allow-listed IP address, the proxy must also accept CONNECT to those ports.
  • Network reachability from the Sandbox node pool to the proxy. The proxy address can be a private IP address or, on LangSmith 0.17.36 or later, an in-cluster Kubernetes Service name such as squid.proxy.svc.cluster.local.
The forward proxy cannot require authentication: sandbox-host does not support proxy credentials in the URL, Basic or NTLM authentication, or client certificates (mTLS). An HTTPS proxy works when the host only needs to trust its server certificate.

​
Configure the proxy

To route Sandbox egress through a forward proxy:
1

Add the proxy settings to your values

Set sandboxes.authProxy.httpProxy in your LangSmith Helm values:
  • enabled: Routes Sandbox egress through the proxy. Defaults to false.
  • scheme: http, or https when the connection to the proxy itself uses TLS. Defaults to http.
  • host: The proxy hostname, IP address, or in-cluster Service name, without a scheme, credentials, or path. Required when enabled is true.
  • port: The proxy port. Defaults to 3128.
  • noProxy: Destinations that the host dials directly instead of through the proxy, with the same matching as the NO_PROXY environment variable. An entry such as corp.internal matches that host and its subdomains, an entry with a leading dot such as .corp.internal matches only subdomains, and * matches every host. Entries can also be IP addresses, CIDR ranges such as 10.0.0.0/8, or host:port pairs.
The chart fails the render when host is missing, when host contains a scheme, credentials, or a path, or when scheme or port is invalid. On LangSmith 0.17.36 or later, sandbox-host also checks the proxy address when it starts: a loopback or cloud metadata address stops the pod with sandbox host config invalid instead of failing each Sandbox creation.
2

(Optional) Trust a private CA for an HTTPS proxy

When scheme is https and a private CA issues the proxy’s certificate, add that CA to the bundle in config.customCa. The sandbox-host pods trust the same bundle as other LangSmith services, in addition to the system roots. See Mount internal CAs for TLS.
3

Apply the change

Upgrade the Helm release. Changing these settings rolls the sandbox-host Deployment, so each host drains its running Sandboxes before it restarts. See Understand a rolling upgrade.
4

Verify egress

Create a Sandbox and request a public URL from inside it:
The command prints 200, and your forward proxy logs a CONNECT www.langchain.com:443 request from a Sandbox node. A request to an http:// URL appears in the proxy log as a GET http://... request instead.

​
Reach private services directly

By default, sandbox-host refuses to connect to private addresses, so a Sandbox cannot reach an internal service even when noProxy sends the connection direct. On a self-hosted installation, a Sandbox reaches a private address when its allow_list lets that destination through: a hostname, a glob such as *.corp.internal, or a regular expression. A literal IP address needs an IP or CIDR entry. Sandboxes with a deny_list or no access_control never reach private addresses. See Allow and deny lists. For example, a Sandbox that needs Git and a database on the internal network, plus public HTTP and HTTPS through the forward proxy, uses this proxy_config:
The host checks the address it connects to after resolving the hostname. Loopback and cloud metadata addresses stay blocked even when listed. This needs no Helm setting. A Sandbox can also reach a Service in your cluster by its Kubernetes name, such as api.team.svc.cluster.local, when its allow_list names it. Your forward proxy cannot resolve cluster names, so add .svc.cluster.local to noProxy when you use one.
Every matching entry counts, including * and *:443. On a self-hosted installation, an allow_list such as ["*:80", "*:443"] also opens private destinations on those ports. Anyone who can create or update a Sandbox can allow-list a private address, including addresses inside your cluster, so limit who can create Sandboxes accordingly.

​
Secure the proxy

The forward proxy, not the host, resolves the destination hostname. The host checks hostnames against the Sandbox access lists and, by default, blocks literal private, loopback, and cloud metadata IP addresses, but it cannot see the address the proxy resolves a hostname to. A Sandbox that requests a hostname resolving to an internal address reaches that address if the proxy allows it. Configure the proxy’s access policy to block the destinations Sandboxes must not reach, such as internal networks and cloud metadata endpoints.

​
Understand the limitations

  • Private services need connectivity: A forward proxy reaches only the destinations the proxy itself can reach. It does not provide VPN or network peering to private services.
  • TLS-inspecting proxies: When the proxy decrypts and re-encrypts HTTPS inside the tunnel, the client sees a certificate from your inspection CA. For hosts that auth proxy rules match, sandbox-host is that client, so add the CA to config.customCa. For other hosts, programs in the Sandbox are the client, so add the CA to the Sandbox image’s trust store. Alternatively, exempt Sandbox traffic from inspection.

​
See also

Connect these docs to your agent of choice via MCP for real-time answers.
Edit this page on GitHub or file an issue.