Tunneld Installer

⚠️ Tunneld is in heavy active development (pre-alpha phase). Expect a lot of breaking changes

A single ARM64 pre-alpha build is published at a time for testing. The source code and versioned releases will become available once the project is opened. For early access and feedback, contact @toreanjoel.

---

Official installer script for Tunneld - a portable, ethernet-first programmable edge relay for self-hosters, developers, and edge network builders.

---

What Tunneld Looks Like

Here is Tunneld in action - exposing a local service to the subnet.

Quick Remote Install

Install Tunneld directly:

curl -fsSL https://install.tunneld.sh -o install.sh
chmod +x install.sh
sudo ./install.sh

Uninstall:

curl -fsSL https://install.tunneld.sh -o uninstall.sh
chmod +x uninstall.sh
sudo ./uninstall.sh

---

Pre-Alpha Builds & Integrity

During the pre-alpha phase, the installer pulls:

• releases/tunneld-pre-alpha.tar.gz
• releases/checksums.txt

The installer:

1. Downloads the tarball
2. Downloads checksums.txt
3. Shows the expected SHA256
4. Attempts verification
5. Extracts into /opt/tunneld

Only one active pre-alpha build exists at any time - each new build replaces the previous one.

Current build: v0.19.21 (Caddy-backed, dual-NIC, runtime-agnostic, WireGuard overlay).

When Tunneld becomes public/open-source, this system will move to signed, tagged semantic releases (e.g. v1.0.0).

---

What is Tunneld?

Tunneld is a portable, self-contained network edge relay that provides:

Local Resource Sharing

Expose local services on the subnet at <name>.tunneld.lan via a Caddy reverse proxy with backend pool load balancing - no port forwarding, no overlay clients required.

Runtime-Agnostic Discovery + WireGuard Overlay

Enroll machines and discover what is listening (ss -tlnp) on them, regardless of runtime (Incus, Docker, systemd, or a bare binary). Promote any listener to a named resource. Remote machines are brought onto a WireGuard overlay (the gateway dials out) so their services are reachable as if local.

Ethernet-First Edge Gateway

A standalone gateway that:

• Acts as its own DHCP server
• Provides an isolated local subnet
• Bridges an upstream internet link to a downstream LAN
• Requires no software installation on client devices

Built-in Network Services

• DNS & DHCP - via dnsmasq, forwarding to user-configured DNS server

All traffic stays local - no reliance on central infrastructure.

---

What the Installer Does

The installer (install.sh) performs a guided setup:

1. Guided Configuration

• Detects network interfaces
• Prompts for:
  • Upstream (internet-facing NIC)
  • Downstream (LAN-facing NIC)
  • Gateway IP
  • DHCP range

2. Installs and Configures Dependencies

Installs:

• dnsmasq
• dhcpcd
• caddy (reverse proxy/load balancer; Tunneld drives its JSON admin API)
• iptables, iproute2, bc, unzip
• systemd-timesyncd
• openssl (for the release's secret key generation)

3. Configures System Services

Creates:

• /etc/tunneld/interfaces.conf
• /etc/tunneld/dnsmasq.conf
• /etc/tunneld/dhcpcd.conf

Symlinks them into place:

• /etc/dhcpcd.conf → /etc/tunneld/dhcpcd.conf
• /etc/dnsmasq.conf → /etc/tunneld/dnsmasq.conf

Notes:

• Tunneld reconciles a single Caddy JSON config (LAN plane on :18000 plus per-resource loopback listeners) through Caddy's admin API.
• dnsmasq resolves any *.tunneld.lan name to the gateway IP (via /etc/dnsmasq.d/tunneld_resources.conf) so named resources and exposed container services are reachable by name across the subnet.

4. Deploys Tunneld

• Optionally downloads the pre-alpha release
• Verifies the checksum
• Extracts files to /opt/tunneld
• Creates a tunneld.service systemd unit
• Restarts all relevant services

Services managed:

tunneld.service
caddy.service
dnsmasq.service
dhcpcd.service

---

After Installation

Access dashboard:

http://10.0.0.1

Verify services:

systemctl status caddy tunneld dnsmasq dhcpcd

---

Uninstallation

curl -fsSL https://raw.githubusercontent.com/toreanjoel/tunneld-installer/main/uninstall.sh -o uninstall.sh
chmod +x uninstall.sh
sudo ./uninstall.sh

The uninstaller will:

1. Stop and disable:

   • tunneld

2. Remove:

/opt/tunneld
/etc/tunneld
/var/lib/tunneld
/var/log/tunneld
/var/run/tunneld

3. Caddy config is managed by Tunneld and reconciled automatically on restart.
4. Remove the systemd unit
5. Remove /etc/dhcpcd.conf or /etc/dnsmasq.conf if they were symlinks to Tunneld
6. Remove dnsmasq drop-ins (tunneld_dns.conf, tunneld_resources.conf)
7. Restart base services (best effort)

Note:
The uninstaller never removes OS packages (dnsmasq, dhcpcd, caddy, iptables, etc.). Remove them manually with apt if desired.

---

Directory Layout

/opt/tunneld/              Application binaries and release files
/etc/tunneld/              Config files
/var/log/tunneld/          Logs
/var/lib/tunneld/          Persistent data
/var/run/tunneld/          Runtime files

---

Key Configuration Files

File	Purpose
interfaces.conf	Interface + subnet config
dhcpcd.conf	Gateway routing (upstream/downstream)
dnsmasq.conf	DNS & DHCP config
Caddy JSON config (Tunneld admin API)	Tunneld reconciles the LAN + loopback planes here

---

Environment Variables

The tunneld.service systemd unit passes these to the app:

Variable	Purpose
UPSTREAM_INTERFACE	Internet-facing NIC (selected during install)
DOWNSTREAM_INTERFACE	LAN-facing NIC (selected during install)
GATEWAY	Gateway IP for the downstream subnet
DEVICE_ID	Unique device identifier (UUID)
TUNNELD_DATA	Persistent data directory (/var/lib/tunneld)
SECRET_KEY_BASE	Phoenix signing key (generated at install time)
PORT	HTTP port for the dashboard (default 80)

Interface names are selected dynamically at install time via a whiptail menu that lists all non-virtual interfaces. They are never hardcoded in the app or the installer.

---

Support the Project

Tunneld builds on:

• dnsmasq
• dhcpcd
• caddy
• iptables
• Elixir / Phoenix

These open-source tools make Tunneld possible.