Secure Tunnel

Set up a Tunnel

Enterprise Feature

Secure tunneling is available as an add-on as part of an enterprise plan. If you would like to purchase this feature, please contact us at sales@zuplo.com or reach out to your account manager.

Most enterprise features can be used in a trial mode for a limited time. Feel free to use enterprise features for development and testing purposes.

This guide takes you from nothing to a working tunnel: you create the tunnel in Zuplo, run the tunnel container inside your network, tell Zuplo which internal services to expose, and confirm the connection is up.

For background on what a tunnel does and how it fits your architecture, see Secure tunnel.

Before you begin

You need:

The Zuplo CLI installed and authenticated.
A Linux host or container runtime inside the network that holds your backend API. The host needs outbound internet access and internal DNS resolution to your backend.
The internal endpoint of each service you want to expose, such as http://payments.internal:8080.

Create the tunnel

Create the tunnel in your Zuplo account:
```
Code
zuplo tunnel create --tunnel-name my-tunnel
```
The command returns the tunnel ID, which starts with tnl_. Record it — the remaining commands need it. To look it up later, run zuplo tunnel list.
Retrieve the tunnel's connection token:
```
Code
zuplo tunnel describe --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx
```
Copy the token value from the output. The tunnel container authenticates with this token.

The token grants the ability to connect to your tunnel. Store it in your platform's secret manager rather than in source control or a plain environment file. If a token is exposed, see Rotate the tunnel token.

Run the tunnel

Deploy the zuplo/tunnel container anywhere inside your network. It takes a single environment variable, TUNNEL_TOKEN, set to the token from the previous step.

To confirm the token works before you wire up your deployment platform, run the container locally on a host inside your network:

Code
docker run -d --name zuplo-tunnel \
  -e TUNNEL_TOKEN=<YOUR_TUNNEL_TOKEN> \
  zuplo/tunnel:latest

Replace <YOUR_TUNNEL_TOKEN> with the token you copied. For production, pin a specific image tag instead of latest and inject the token from your secret manager. For details, see Advanced tunnel configuration.

Run at least two instances so the tunnel survives the loss of a single host or pod. Instances that share the same token act as replicas of one tunnel.

Where you deploy depends on your infrastructure. The following guides cover the common platforms:

For help with a platform that isn't listed, contact Zuplo support.

Expose your internal services

A running tunnel doesn't expose anything by itself. You define the services it forwards to in a configuration file, then upload that file to Zuplo.

Create a configuration file that names each service, its internal endpoint, and the Zuplo projects and environments allowed to call it:


Code
{
  "version": 1,
  "services": [
    {
      "name": "payments-api-prod",
      "endpoint": "http://payments.internal:8080",
      "configurations": [
        {
          "project": "my-project",
          "accessibleBy": ["production"]
        }
      ]
    },
    {
      "name": "payments-api-staging",
      "endpoint": "http://payments-staging.internal:8080",
      "configurations": [
        {
          "project": "my-project",
          "accessibleBy": ["preview", "working-copy"]
        }
      ]
    }
  ]
}

For the meaning of each property, see Service configuration reference.

Upload the configuration to your tunnel:
```
Code
zuplo tunnel services update \
  --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx \
  --configuration-file ./tunnel-config.json
```
The upload replaces the tunnel's entire service configuration, so include every service you want available each time you run it.

Verify the tunnel

Check that the tunnel reports itself as connected:
```
Code
zuplo tunnel describe --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx
```
Look at the status field. A new tunnel takes a few seconds to register the first time it connects. If the status stays down, see Troubleshoot a tunnel.

Confirm Zuplo has the services you uploaded:

Code
zuplo tunnel services describe --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx

Call a service from your gateway. Add a route to your project that rewrites to one of your service URLs, such as service://payments-api-prod, and send a request to it. For the full set of ways to call a service, see Connect to tunnel services.

Next steps

Connect to tunnel services — call service:// URLs from handler code, route configuration, and environment variables.
Advanced tunnel configuration — pin image versions, tune the connection, rotate tokens, and build your own image.
Troubleshoot a tunnel — work through a tunnel that's down or not passing traffic.

Edit this page

Last modified on August 5, 2026

Overview Connect to Services