Agent guide
The agent is the part that runs on your own machine — the one with the service you want to share. It opens an outgoing connection to your server and keeps it open. No ports are opened on your machine, no router changes needed: nothing works until the agent calls home, and once it does, visitors reach your service through your server's domain.
The agent and the server are the same single binary. On the machine with your service you run:
tunnel-me connect -u <server-url> -t <token> <upstream>
Aliases to and agent do the same thing as connect.
The upstream — what to share
The last argument says what visitors should reach. Three forms, plus a default:
| Upstream | Example | Meaning |
|---|---|---|
| Port | 3000 |
A service running on the same machine |
host:port |
localhost:3000, 192.168.1.50:8123 |
A service on this machine or anywhere your machine can reach — another box on your LAN, a NAS, anything |
| Directory | ./my-site |
Serve a folder of files as a simple website |
| (omitted) | — | Serve the current directory |
The panel builds these commands for you: open the tunnel's Overview tab, pick what you are sharing, and copy the command.
Flags
| Flag | Environment variable | Default | What it does |
|---|---|---|---|
-u, --url |
TUNNEL_URL |
http://localhost:8080 |
Your server's address. Pass just the base URL — the agent attaches the rest itself |
-t, --token |
TUNNEL_TOKEN |
— | Token for this tunnel, from the panel. Required |
-r, --reconnect |
TUNNEL_RECONNECT |
1s |
How often to retry after the connection drops |
-T, --tls |
TUNNEL_TLS |
off | Your local service itself speaks HTTPS |
--timeout |
TUNNEL_TIMEOUT |
10s |
How long to wait when connecting to the local service |
Getting the binary
The easy way — from the panel (Agents → your tunnel → Overview) copy the one-line install command:
curl -fsSL https://tunnels.example.com/boot/connect/<token> | sh -s -- <upstream>
It detects your platform, downloads the binary to ~/.local/bin/tunnel-me (only if it is not there yet), and starts the agent in the foreground. Linux and macOS, x86_64 and arm64.
Updating later: the installer skips the download when
~/.local/bin/tunnel-mealready exists. Delete that file first to get the new version.
Manual — download a binary straight from your server, replacing the platform as needed:
curl -fsSL -o tunnel-me https://tunnels.example.com/boot/instance/linux/amd64
chmod +x tunnel-me
From releases — the project's GitHub Releases page publishes ready-made archives (Linux/macOS, x86_64/arm64) for every release. Any of these binaries works against any tunnel-me server.
Docker — the same official image runs the agent when you override the command:
docker run -d --name tunnel-me-agent \
--network host \
--restart unless-stopped \
ghcr.io/reddec/tunnel-me connect -u https://tunnels.example.com -t <token> 3000
--network host (Linux) lets the container reach services on the machine itself and your LAN. Without it, use the container-visible address of your service instead — for example host.docker.internal:3000 on Docker Desktop.
Keeping it running
The agent is a foreground program — closing the terminal stops it. For an always-on setup run it under systemd (Linux) or as a LaunchAgent (macOS).
A systemd unit, stored as /etc/systemd/system/tunnel-me-agent.service:
[Unit]
Description=tunnel-me agent
After=network-online.target
Wants=network-online.target
[Service]
# /etc/tunnel-me.env contains:
# TUNNEL_URL=https://tunnels.example.com
# TUNNEL_TOKEN=<token>
EnvironmentFile=/etc/tunnel-me.env
ExecStart=/usr/local/bin/tunnel-me connect 3000
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
Keep the env file readable only by root (chmod 600) since it holds the token, then:
sudo systemctl daemon-reload
sudo systemctl enable --now tunnel-me-agent
Behavior worth knowing
- The agent reconnects forever. Kill your internet, reboot your router, restart the machine — the agent retries every
--reconnectuntil the connection is back. Restarting it at any time is safe. - No local state. There is no config file or state on the agent; everything lives on the server. The agent learns its public address (
myapp.tunnels.example.com) from the server during the handshake and logs it, so the log always tells you where visitors reach this service. - Any number of agents per tunnel. A token is not a lease — the same token can be used by any number of machines and connections at once, and the server alternates visitor requests between everything currently connected. This is how auto-scaled setups work: an agent sidecar per replica, all sharing one token. Extra tokens are for control, not necessity — separate tokens per machine or app let you revoke a single player without touching the rest.
- Tokens are shown once. Copy the token when the panel reveals it. If it is lost, delete it and create a new one; deleting a token also disconnects the machines that logged in with it.
Platforms: Linux and macOS on x86_64 and arm64.