Tunnels

A tunnel lets LangSmith reach a service that runs on your private network, such as a model endpoint or an MCP server, without opening that service to the internet. You run a small connector inside your network. The connector opens an outbound connection to LangSmith, and LangSmith sends requests for your service over that connection. Tunnels are available on LangSmith Cloud in every region. They are not available for self-hosted or hybrid deployments.

​

How tunnels work

1. An organization admin creates a tunnel in LangSmith.
2. You run the connector inside your network and configure it with the tunnel’s ID, an API key, and one or more targets. A target is a name mapped to a private address, for example litellm mapped to http://litellm.internal:4000.
3. The connector connects outbound to LangSmith over HTTPS (port 443). Nothing connects in to your network, and the connector exposes no ports.
4. Each HTTP target gets a tunnel URL. You use that URL in LangSmith wherever you would use the service’s address.
5. When a LangSmith feature calls a tunnel URL, LangSmith checks that the caller belongs to the tunnel’s organization and sends the request to the connector, which forwards it to the target.

​

Set up a tunnel

To create a tunnel, you need the Organization Admin or Organization Operator role. You also need a place inside your network to run the connector: a Kubernetes cluster or a Docker host that can reach your services and make outbound HTTPS connections.

​

Targets

Each target is a name and an address:

• Name: 1 to 63 characters. It starts with a lowercase letter and contains only lowercase letters, digits, and underscores.
• Address: http://host:port or https://host:port, with no path. LangSmith can reach only HTTP and HTTPS targets.

A connector can serve up to 256 targets. To add or change targets, update the connector’s configuration and restart it, for example with helm upgrade.

​

Use a tunnel URL

Select Copy tunnel URL next to a target to copy its URL. Tunnel URLs look like https://<handle>.tunnels.smith.langchain.com, with the region in the domain for other regions (for example, tunnels.eu.smith.langchain.com). You can also list a tunnel’s targets and URLs with GET /v1/connections/{tunnel_id}/targets. You can use a tunnel URL in place of a service address in:

• Model configurations and custom model endpoints, as the base URL. This covers the Playground, experiments, and online evaluators that use the model.
• LangSmith Fleet, as a model’s base URL or an MCP server URL.
• MCP servers that use OAuth, for the token endpoint. The authorization endpoint must stay reachable from the browser, so it cannot be a tunnel URL.

Keep the following in mind:

• Tunnel URLs use HTTPS only.
• Requests through a tunnel do not follow redirects.
• A model reached through a tunnel needs its own API key in its configuration. LLM auth proxy credentials are not sent through a tunnel.
• Your target must start responding within 30 seconds. A single request can stream for up to 1 hour, and request bodies can be up to 32 MiB.

​

Security

​

Outbound-only connection

The connector makes an outbound WebSocket connection over TLS to your region’s LangSmith API endpoint on port 443. You do not open inbound ports or change firewall rules for LangSmith, and the connector pod exposes no ports.

​

Authentication and authorization

• Connector: The connector authenticates with an organization API key that has permission to connect tunnels. LangSmith accepts the connector only while the tunnel is enabled.
• Each request: LangSmith authorizes every request to a tunnel URL. The caller must be a LangSmith service acting for a member of the tunnel’s organization, or must present an API key for that organization. The tunnel must be enabled. A tunnel URL is not a secret and grants no access by itself.

​

What your network exposes

• LangSmith sends the connector only a target name. The connector looks the name up in its own configuration and refuses names it does not have, so LangSmith can reach only the targets you configure.
• The connector does not connect to cloud metadata addresses.
• For HTTP targets, the target’s host and port are shared with LangSmith so requests carry the right Host header.

​

Headers

LangSmith removes its own credentials and identity headers before a request reaches your service: X-Service-Key, X-Api-Key, X-Tenant-Id, X-Organization-Id, X-User-Id, X-Data-Plane-Auth, Cookie, and any header that starts with X-Langsmith- or X-Langchain-. Authorization passes through, so a service that authenticates with a bearer token works without changes. If your service authenticates with its own X-Api-Key or Cookie header, LangSmith features deliver the header you configure to your service. Headers named after LangSmith’s identity headers, such as X-Tenant-Id, never reach your service.

​

Encryption

• Traffic between LangSmith and the connector travels inside the TLS-encrypted WebSocket connection.
• LangSmith terminates TLS for tunnel URLs and handles each request in memory to route it to your connector.
• Between the connector and your service, use an https:// target to encrypt traffic. The connector verifies the service’s certificate against the system certificate authorities. To trust a private certificate authority, set SSL_CERT_FILE on the connector. Traffic to http:// targets is not encrypted inside your network.

​

Logging and data storage

LangSmith does not log request or response bodies sent through a tunnel. For failed requests, LangSmith logs the tunnel, organization, target, status, and error. LangSmith stores only the routing information needed to reach your connector. The connector does not log request or response bodies either. By default it logs only failures, such as a target it cannot reach. At debug level, it also logs each request’s target, address, duration, and size.

​

Revoke access

To stop LangSmith from reaching your services, disable or delete the tunnel in Settings > Tunnels. LangSmith then rejects requests to its tunnel URLs and refuses new connector connections. You can also stop the connector, or revoke its API key.

---