Set up Tunnels

What this enables

Tunnels must be enabled for your workspace. If Tunnels is unavailable in your workspace settings, contact Replit to confirm availability and enablement.

A tunnel lets a supported Replit Development Environment reach an approved TCP destination in your private network through a connector you operate. This is an alternative connectivity approach to allowing sandbox egress IPs into your network. Run the connector in a network where it can resolve and reach your private TCP services. You can use the generated Docker command or deploy the connector on Kubernetes with the Helm chart below. Replit operates the tunnel control plane. The chart below deploys only your connector. Connection path: Replit project → Replit tunnel infrastructure → your connector → private TCP service. Service authentication and TLS remain independent of tunnel enrollment.

1. Create the tunnel in Replit

In Replit, use the workspace selector to choose the workspace that owns your projects. Open Settings → Workspace overview and scroll to Tunnels.

Open the Tunnels section in your workspace settings.

Click Create tunnel and enter a descriptive name.

In the Save your enrollment key dialog, use the copy buttons beside Tunnel ID and Enrollment key. Save the enrollment key in your approved secrets manager before clicking I’ve saved my key. The key is shown only once and cannot be viewed again after closing this dialog.

The one-time enrollment-key dialog. The key is intentionally hidden in this screenshot.

Open Settings → Workspace overview → Tunnels and select your tunnel. Its ID appears beneath the tunnel name with a copy button. Before the connector is online, the Complete tunnel setup panel shows the Docker command. Replace the enrollment-key placeholder with the key you saved.

Copy the Docker command from Complete tunnel setup.

For Helm, copy the full RPTUN_TUNNEL_REF and RPTUN_ENROLL_ADDR values from the setup command into tunnelRef and enrollAddr. Copy the container image from the command’s final line into image. The full tunnel reference is different from the short tunnel ID shown beneath the tunnel name. The enrollment key comes from the one-time key dialog, not from the setup command. Run the Docker command on a host that can resolve and reach your private service. For Kubernetes, use the Helm chart below.

2. Deploy the connector with Helm

This example chart runs the customer-side connector on Kubernetes. Adapt it to your cluster’s standards and validate it in a non-production environment before you roll it out.

Create the chart files

Create this directory structure:

replit-tunnel-connector/
  Chart.yaml
  values.yaml
  templates/
    deployment.yaml
customer-values.yaml

mkdir -p replit-tunnel-connector/templates

replit-tunnel-connector/Chart.yaml

apiVersion: v2
name: replit-tunnel-connector
description: Example customer-side Replit tunnel connector.
type: application
version: 0.1.0

replit-tunnel-connector/values.yaml

# Use the image and connection settings from your own tunnel's setup panel.
# Do not put enrollment keys in Helm values or --set arguments.
image: ""
tunnelRef: ""
enrollAddr: ""
existingSecret: replit-tunnel-enrollment
secretKey: enrollment-key
resources: {}
nodeSelector: {}
tolerations: []
affinity: {}

replit-tunnel-connector/templates/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}
  labels:
    app.kubernetes.io/name: replit-tunnel-connector
    app.kubernetes.io/instance: {{ .Release.Name }}
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app.kubernetes.io/name: replit-tunnel-connector
      app.kubernetes.io/instance: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app.kubernetes.io/name: replit-tunnel-connector
        app.kubernetes.io/instance: {{ .Release.Name }}
    spec:
      automountServiceAccountToken: false
      containers:
        - name: connector
          image: {{ required "Set image to the connector image from your tunnel setup panel" .Values.image | quote }}
          imagePullPolicy: IfNotPresent
          env:
            - name: RPTUN_ENROLLMENT_KEY
              valueFrom:
                secretKeyRef:
                  name: {{ required "Set existingSecret" .Values.existingSecret | quote }}
                  key: {{ required "Set secretKey" .Values.secretKey | quote }}
            - name: RPTUN_TUNNEL_REF
              value: {{ required "Set tunnelRef from your tunnel setup panel" .Values.tunnelRef | quote }}
            - name: RPTUN_ENROLL_ADDR
              value: {{ required "Set enrollAddr from your tunnel setup panel" .Values.enrollAddr | quote }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
      nodeSelector:
        {{- toYaml .Values.nodeSelector | nindent 8 }}
      tolerations:
        {{- toYaml .Values.tolerations | nindent 8 }}
      affinity:
        {{- toYaml .Values.affinity | nindent 8 }}

Configure your tunnel

Create the namespace and provision the enrollment key through your approved secret-management process. The example expects a Secret named replit-tunnel-enrollment with a field named enrollment-key in namespace replit-tunnels. Do not put the enrollment key in Helm values, source control, or --set arguments. customer-values.yaml — replace the three placeholders using your own tunnel’s generated setup command:

# Replace all three placeholders using your own tunnel's setup command.
image: "CONNECTOR_IMAGE_FROM_REPLIT"
tunnelRef: "TUNNEL_REFERENCE_FROM_REPLIT"
enrollAddr: "ENROLLMENT_ADDRESS_FROM_REPLIT"
existingSecret: replit-tunnel-enrollment
secretKey: enrollment-key

Use an approved immutable connector image digest for production where available. The chart preserves the image entry point and passes the environment variables shown in the generated Docker command. Validate compatibility with your exact image.

Render and install

With Helm and kubectl configured for your intended Kubernetes cluster, run these commands from the directory containing customer-values.yaml and the chart directory. The namespace and Secret must already exist:

helm lint ./replit-tunnel-connector -f customer-values.yaml
helm template replit-tunnel ./replit-tunnel-connector \
  --namespace replit-tunnels -f customer-values.yaml
helm upgrade --install replit-tunnel ./replit-tunnel-connector \
  --namespace replit-tunnels -f customer-values.yaml \
  --wait --timeout 5m
kubectl -n replit-tunnels rollout status deployment/replit-tunnel
kubectl -n replit-tunnels get pods -l app.kubernetes.io/instance=replit-tunnel

The chart runs one replica with the Recreate strategy, so updates cause downtime. It creates no public Service or LoadBalancer and defines no health probes. Kubernetes readiness alone does not prove tunnel connectivity: confirm Online in Replit and complete the project Shell tests below. Before production use, validate resources, CPU architecture, writable-state needs, security context, restart behavior and outbound network requirements. The connector must reach your private service’s DNS hostname and TCP port. Obtain the complete connector egress requirements from Replit. For troubleshooting, review logs locally and redact credentials and private information before sharing:

kubectl -n replit-tunnels logs deployment/replit-tunnel --tail=100

3. Confirm the connector is online

Return to Settings → Workspace overview → Tunnels and select your tunnel. Wait for the Status card to show Online. If it stays offline, check enrollment configuration, outbound network access, pod events, and connector logs.

Online means the connector is connected. Never is expected before any application traffic.

4. Register a private endpoint

On the tunnel details page, click Add endpoint in the Endpoints section.
Enter a descriptive name and the private destination hostname with its TCP port, for example database.internal.example:5432.
Use a hostname resolvable from the connector’s network. The current UI does not support IP-address destinations.
Select Test connection. A green check means the connector can reach the destination.
Add the endpoint and confirm it appears in the table.

Successful connection test: the green check beside Destination confirms the connector can reach the service.

The endpoint appears in the table, where you can copy its destination or open its three-dot actions menu.

Saved Redis endpoint with the connector Online and destination Reachable.

5. Verify endpoint resolution in a Replit project Shell

Use the workspace selector to return to the workspace that owns the tunnel, open a project there, and open the Shell tab in the project editor. Run the following checks in that Shell, not in a standalone chat.

Confirm the hostname resolves

Use the hostname from the endpoint’s Destination field without the port or a URL scheme:

getent hosts YOUR_ENDPOINT_HOSTNAME

A successful lookup prints an IP address and the hostname. DNS resolution alone does not confirm service connectivity; run the service test below next.

Test the service connection

Use your service’s native client for a lightweight request, with its normal TLS and authentication requirements. For Redis:

redis-cli -h YOUR_ENDPOINT_HOSTNAME -p 6379 PING

6379 is Redis’s default port. Replace it if needed to match the port of your registered endpoint. Expected result: PONG. This is Redis’s application-level PING, not ICMP network ping.

Hostname resolution and a successful Redis PONG in the project Shell.

After a successful request, the tunnel dashboard now shows recent traffic timestamps.

Tunnel activity after the successful Redis request.

6. Manage enrollment keys

Back in the tunnels dashboard, open the three-dot menu beside the tunnel name and select Manage enrollment key.

Add an enrollment key

Choose Add enrollment key when a slot is available. It opens the same Save your enrollment key dialog shown during initial setup. Copy the new key immediately and save it securely: it is shown only once. If both key slots are occupied, identify the key to revoke or replace before continuing. Do not revoke a key blindly. Retry key delivery is for an interrupted request, not for displaying a previously delivered key again.

Revoke an enrollment key

Choose Revoke on the intended key, check the selected key details, and choose Confirm selected key revocation. This blocks future enrollment using that key.

Revoking a key does not disconnect established connector sessions. Restart the connector with a new key to end existing sessions.

Review and confirm revocation of the selected key.

After revocation, the active key count updates. The established connector can still be Online.

Update a connector after changing its key

Provision the new key through your approved secrets manager. Restart the connector deployment after the Secret update:

kubectl -n replit-tunnels rollout restart deployment/replit-tunnel
kubectl -n replit-tunnels rollout status deployment/replit-tunnel

Confirm Online and repeat the project Shell service request. Plan for downtime with this example’s single-replica Recreate strategy. Do not assume that revocation alone terminates an existing connection.

7. Disconnect and clean up

When the connector stops, the tunnel becomes Offline and the endpoint should not be treated as reachable.

Tunnel Offline and endpoint Unreachable after disconnecting the connector.

To remove the connector’s Helm release:

helm uninstall replit-tunnel --namespace replit-tunnels

The chart does not manage the Secret, namespace, Replit tunnel, or endpoints. Remove those separately only when they are no longer needed. Never remove a shared namespace or another application’s endpoint.

Troubleshooting

Tunnels unavailable

Ask Replit to verify workspace enablement and service availability before changing your connector or network configuration.

Connector pod fails

Inspect image pull, scheduling, Secret references, and container startup errors.

Tunnel offline

Inspect enrollment configuration and connector outbound connectivity.

Endpoint unreachable

Check private DNS, the target service and port, routing, firewall rules, and any Kubernetes NetworkPolicies from the connector’s network.

Connection test succeeds but query fails

Check database TLS, credentials, database permissions, and the supported Replit sandbox routing path.

Duplicate destination

Check existing endpoints across the workspace before creating another registration.

Hostname does not resolve

Confirm you are in a Replit project Shell in the same workspace as the saved endpoint. Check the exact destination hostname and tunnel status. If it persists, contact Replit with the workspace/project and error. Never share the enrollment key.

​What this enables

​1. Create the tunnel in Replit

​2. Deploy the connector with Helm

​Create the chart files

​Configure your tunnel

​Render and install

​3. Confirm the connector is online

​4. Register a private endpoint

​5. Verify endpoint resolution in a Replit project Shell

​Confirm the hostname resolves

​Test the service connection

​6. Manage enrollment keys

​Add an enrollment key

​Revoke an enrollment key

​Update a connector after changing its key

​7. Disconnect and clean up

​Troubleshooting

​Tunnels unavailable

​Connector pod fails

​Tunnel offline

​Endpoint unreachable

​Connection test succeeds but query fails

​Duplicate destination

​Hostname does not resolve

What this enables

1. Create the tunnel in Replit

2. Deploy the connector with Helm

Create the chart files

Configure your tunnel

Render and install

3. Confirm the connector is online

4. Register a private endpoint

5. Verify endpoint resolution in a Replit project Shell

Confirm the hostname resolves

Test the service connection

6. Manage enrollment keys

Add an enrollment key

Revoke an enrollment key

Update a connector after changing its key

7. Disconnect and clean up

Troubleshooting

Tunnels unavailable

Connector pod fails

Tunnel offline

Endpoint unreachable

Connection test succeeds but query fails

Duplicate destination

Hostname does not resolve