Skip to content

Getting Started

Quick Start

# Pull the image
docker pull sudocarlos/tailrelay:latest

# Run the container
docker run -d --name tailrelay \
  -v /path/to/data:/var/lib/tailscale \
  -e TS_HOSTNAME=myserver \
  -p 8021:8021 \
  --net bridge \
  sudocarlos/tailrelay:latest

# Access the Web UI and follow the Tailscale login link
open http://localhost:8021

Prerequisites

  1. A Tailscale account with an active Tailnet (tailscale.com)
  2. HTTPS certificates enabled in the Tailscale Admin console
  3. Docker or Podman installed

Tailscale Setup

  1. Log into the Tailscale Admin console and open DNS to enable MagicDNS.
  2. Tailnets created on or after October 20, 2022 have MagicDNS enabled by default.
  3. Review MagicDNS to understand how it works.
  4. Verify or set your Tailnet name.
  5. Scroll down and enable HTTPS under HTTPS Certificates.

Using a Custom Control Server (Headscale)

If you run a self-hosted Headscale instance instead of Tailscale's coordination server, set its URL in the Control Server field on the Tailscale page's connection status card before logging in. This is applied as tailscale login --login-server=<url> (or tailscale up --authkey=<key> --login-server=<url> for the auth-key flow) and persists across container restarts.

Leave the field empty to use Tailscale's official control plane. Since a device is bound to whichever control server it first authenticated with, switching an already-connected device requires logging out first.

StartOS Deployment

Tailrelay is available as a StartOS package via sudocarlos/tailrelay-startos.

Sideloading:

  1. Download the latest tailrelay.s9pk from the tailrelay-startos releases page, or clone the repo and run make to build it yourself.
  2. In the StartOS web UI menu, navigate to System → Sideload Service.
  3. Drag and drop or select the tailrelay.s9pk file to install.
  4. Once installed, navigate to Services → Tailrelay and click Start.

Next Steps