Quickstart

This path assumes you have a Linux edge server, a DNS zone you control, and SSH access from the client machine to the edge. Replace tunnel.example.com and mytunnel-edge with your domain and SSH alias or user@host.

1. Point wildcard DNS at the edge

Create a wildcard record where your DNS zone is hosted:

*.tunnel.example.com  A     <EDGE_IPV4>
*.tunnel.example.com  AAAA  <EDGE_IPV6>  # optional

The DNS provider matters for ACME DNS challenge support. It is the provider hosting the zone, not necessarily the registrar where you bought the domain.

2. Clone and build

Use local Go when available:

git clone <repo-url> tunneled
cd tunneled
make build

Or build with Docker:

git clone <repo-url> tunneled
cd tunneled
mkdir -p bin
docker run --rm -v "$PWD":/workspace -w /workspace golang:1.25 \
  sh -lc 'export PATH=/usr/local/go/bin:$PATH; go build -o bin/mytunnel ./cmd/mytunnel && go build -o bin/mytunneld ./cmd/mytunneld'

Check the version that was built:

cat VERSION
./bin/mytunnel --version
./bin/mytunneld --version

3. Install the edge daemon

Copy or build the repo on the edge, then run the installer as root. The default Caddy path is opinionated for Infomaniak DNS.

cd ~/tunneled
sudo ./scripts/install-edge.sh \
  --base-domain tunnel.example.com \
  --binary ./bin/mytunneld \
  --infomaniak-token '<INFOMANIAK_API_TOKEN>'

If your DNS provider is not Infomaniak, use --skip-caddy, install Caddy with the right DNS module, then run the edge bootstrap.

sudo ./scripts/install-edge.sh \
  --base-domain tunnel.example.com \
  --binary ./bin/mytunneld \
  --skip-caddy

4. Install the client binary

On the client/source machine:

cd ~/tunneled
./scripts/install-local.sh --binary ./bin/mytunnel

The script installs /usr/local/bin/mytunnel. It uses sudo if the current user is not root.

5. Run read-only checks

On the edge:

sudo ./scripts/check-edge.sh

On the client:

./scripts/check-client.sh --edge mytunnel-edge

check-edge.sh and check-client.sh report issues without changing firewall, SSH, Caddy, or daemon configuration.

6. Start a local HTTP server

If you do not already have an app on port 3000, start a temporary one:

python3 -m http.server 3000

In another terminal, start the tunnel:

mytunnel http 3000 --edge mytunnel-edge --base-domain tunnel.example.com --name portal

Expected output:

url: https://portal.tunnel.example.com
lease: <id>

Open the URL. The first TLS request can take a few seconds while Caddy completes certificate issuance.

7. Stop and clean up

Press Ctrl-C in the mytunnel http terminal. The client retries lease release on shutdown.

If a stale lease remains, remove it:

mytunnel ls --edge mytunnel-edge
mytunnel rm portal --edge mytunnel-edge

What this quickstart does not validate

The quickstart does not prove firewall policy, external Caddy Admin API exposure, real provider token scope, or rollback behavior. Run real system validation before using an edge host for other people.