Skip to main content

Documentation

Tailscale

2 min readEdit on GitHub

Access your Lights Pi from anywhere using Tailscale, a zero-config mesh VPN built on WireGuard. No port forwarding, no dynamic DNS, no firewall holes needed.

Why Tailscale?

  • Access from anywhere — Control lights from your phone at home, a laptop at a café, or backstage at a different venue
  • Zero network config — Works through NATs and firewalls automatically
  • Encrypted — All traffic is WireGuard-encrypted end-to-end
  • Free — Personal plan supports up to 100 devices

Installation

Prerequisites

  • A Tailscale account (free)
  • SSH access to your Pi (./lightsctl.sh ssh)
  • Tailscale on at least one other device (phone, laptop)

Install on the Pi

bash
1./lightsctl.sh ssh
2
3# On the Pi:
4curl -fsSL https://tailscale.com/install.sh | sh
5sudo systemctl enable --now tailscaled
6sudo tailscale up

Open the printed URL in your browser to authorize the device.

Verify

bash
tailscale status

Your Pi should appear with a 100.x.x.x Tailscale IP.

Accessing Services

Once connected, all services are reachable via Tailscale IP or MagicDNS:

ServiceLocalTailscale
Landing pagehttp://lights.localhttp://lights.<tailnet>.ts.net
QLC+ Web UIhttp://lights.local:9999http://lights.<tailnet>.ts.net:9999
Control Serverhttp://lights.local:5000http://lights.<tailnet>.ts.net:5000
MCP Serverhttp://lights.local:5001http://lights.<tailnet>.ts.net:5001
SSHssh pi@lights.localssh pi@lights.<tailnet>.ts.net

MagicDNS uses the Pi's hostname. If hostname returns lights, the MagicDNS name is lights.<your-tailnet>.ts.net.

Firewall Notes

Tailscale operates on the tailscale0 virtual interface and bypasses ufw rules by default. Your existing firewall configuration stays unchanged.

For per-device access restrictions, use Tailscale ACLs in your admin console.

Sharing Access (Tailscale Funnel)

Temporarily share access with someone NOT on your tailnet:

bash
1# On the Pi — expose the control server publicly
2sudo tailscale funnel 5000
3
4# Remove when done
5sudo tailscale funnel --remove 5000

⚠️ Funnel exposes the service to the public internet. Use temporarily and only for non-sensitive services.

MCP Agents Over Tailscale

If you've installed the MCP server, Claude Desktop or other agents can connect over Tailscale by pointing their MCP config at the Tailscale address:

json
1{
2  "mcpServers": {
3    "lights-pi": {
4      "transport": "streamable-http",
5      "url": "http://lights.<tailnet>.ts.net:5001/mcp"
6    }
7  }
8}

This works from anywhere — home, office, or mobile.

Troubleshooting

Pi Not Appearing in Tailnet

bash
sudo systemctl status tailscaled
sudo tailscale up --reset    # Re-authenticate

MagicDNS Not Resolving

Enable MagicDNS in your Tailscale admin console.

High Latency

Check connection type:

bash
tailscale ping lights

Look for "direct" (fast) vs "via DERP" (relay, slower). Ensure UDP port 41641 is allowed on both ends for direct connections.

Uninstalling

bash
sudo tailscale down
sudo apt remove tailscale
sudo rm /etc/apt/sources.list.d/tailscale.list

Was this page helpful?