Configuration

Run several tunnels from a rl-tunnel.yml file, set options with environment variables and use tokens in CI.

1 min read

For one tunnel, flags are enough. When you work with several services, describe them once in a rl-tunnel.yml file at the root of your project.

The rl-tunnel.yml file

rl-tunnel.yml

# rl-tunnel.ymlversion: 1tunnels:  web:    proto: http    port: 3000    subdomain: my-app            # reserved in your dashboard  api:    proto: http    port: 8080    subdomain: my-app-api    auth: "admin:${API_PASSWORD}" # read from the environment, never commit the password    allow_ip: ["203.0.113.0/24"]    no_body: true  db:    proto: tcp    port: 5432

Fields of each tunnel

reference

proto: http | tcp          # requiredport: 3000                 # requiredhost: 192.168.0.20         # optional, default localhostsubdomain: my-app          # http only; must be reserved in your accountauth: "user:pass"          # http only; ${VAR} is expanded from the environmentallow_ip: ["203.0.113.7"]  # IPs or CIDRshost_header: app.local     # http onlyno_body: true              # don't capture bodies in the inspector

Starting tunnels

terminal

# Start every tunnel in the filerl-tunnel start --all# Or only some of themrl-tunnel start web api# A file in another placerl-tunnel start --all --config ./infra/rl-tunnel.yml

Each line of the log is prefixed with the tunnel name, like [web]. If one tunnel fails for good (for example, a subdomain you did not reserve), all tunnels are stopped and the error says which one failed, so you never end up with a half-started set. Temporary network drops are retried per tunnel.

Environment variables

terminal

export RL_TUNNEL_TOKEN=rlt_xxxxxxxxxxxx   # access token (CI, servers)export RL_TUNNEL_NO_UPDATE_CHECK=1        # silence the new-version noticeexport RL_TUNNEL_HISTORY=/path/history     # where inspect/replay keep requestsexport RL_TUNNEL_NO_HISTORY=1             # don't keep requests on diskexport NO_COLOR=1                         # no colors in the terminal

Host header

Some apps (multi-tenant, virtual hosts) depend on the Host header. Rewrite it with --host-header or host_header:

terminal

# Rewrite the Host header for apps that depend on it (vhosts, multi-tenant)rl-tunnel http 3000 --host-header app.local

Using it in CI

Create a token in your dashboard and store it as a secret. No browser login is required:

.github/workflows/preview.yml

# .github/workflows/preview.yml- name: Open preview tunnel  env:    RL_TUNNEL_TOKEN: ${{ secrets.RL_TUNNEL_TOKEN }}  run: |    npm install -g resolvelabs-tunnel    rl-tunnel http 3000 --no-body &