Tailscale Private Networking

Tailscale provides a private mesh VPN that lets you access your Companion Hub apps from anywhere — without exposing them to the public internet.

When to Use Tailscale

Tailscale is ideal when:

You want private access to your apps from your devices only
You don’t want apps publicly accessible on the internet
You need to connect multiple machines in a private network
You want to access your Hub from anywhere securely

Benefits

✅ Access from Anywhere — Securely reach your Hub from any location
✅ Connect All Devices — Link Windows, Mac, Linux, iOS, and Android devices
✅ Zero Configuration — Automatic NAT traversal, no port forwarding needed
✅ Enterprise Security — End-to-end encryption for all traffic
✅ Free for Personal Use — Up to 100 devices on the free tier

Setup Options

Companion Hub offers two ways to use Tailscale:

Option 1: Hub Sidecar (Recommended)

The easiest way — Companion Hub includes a built-in Tailscale container that connects your Hub to your Tailscale network.

Enable During Onboarding

When you first set up your Hub, the onboarding wizard includes a Private VPN step:

Click Log In with Tailscale
Authenticate in the popup window (create a free account if needed)
Your Hub automatically joins your Tailscale network
Continue with the wizard

The onboarding wizard polls connection status in real-time, so you’ll see when your Hub connects successfully.

Enable in Settings

If you skipped Tailscale during onboarding, you can set it up later:

Go to Settings → Network
Find the Private VPN section
Click Log In with Tailscale
Authenticate in the popup window

Access Your Hub

Once connected, your Hub gets a Tailscale IP address (e.g., 100.x.y.z). You can see it in Settings → Network.

Install Tailscale on your other devices:

Download from tailscale.com/download
Log in with the same account
Access your Hub via its Tailscale IP or hostname

Option 2: Host Installation

For advanced users who prefer to install Tailscale directly on the host machine:

Install Tailscale on Host


curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Mount the Socket

Ensure /var/run/tailscale/tailscaled.sock is accessible to the Hub container. The Hub will automatically detect and use the host Tailscale installation.

Access Your Hub

Your Companion Hub dashboard and all apps will be accessible via the Tailscale IP.

How It Works

Mesh Network — Tailscale creates a peer-to-peer mesh between all your devices
NAT Traversal — Works behind firewalls and routers without configuration
Private IPs — Each device gets a private IP (100.x.y.z range)
Encrypted — All traffic is encrypted end-to-end using WireGuard

Troubleshooting

Sidecar Not Available

If you see “Tailscale sidecar container is not running”:

Ensure the private-vpn profile is enabled:


docker compose --profile private-vpn up -d

Or use the Hub CLI (Tailscale sidecar is enabled by default):


cihub up --detached
cihub status    # shows Tailscale IP when connected

Check that the hub-tailscale container is running:
```
docker ps | grep hub-tailscale
```

Connection Not Working

If the login button doesn’t connect:

Complete the authentication in the popup window
Wait 5-10 seconds for the connection to establish
Refresh the Settings page to see updated status

Can’t Access Hub from Other Devices

Verify Tailscale is running on both devices:
```
tailscale status
```
Ensure both devices show “Running” in Tailscale
Try accessing by IP first: http://100.x.y.z (find IP in Settings → Network)
Try accessing by hostname: http://your-hub-name

Advanced Configuration

Custom Routes

By default, the Hub advertises the Docker bridge network (172.18.0.0/16) so other Tailscale devices can reach your containers directly.

To customize this, set HUB_TAILSCALE_EXTRA_ARGS in your .env file:


HUB_TAILSCALE_EXTRA_ARGS=--accept-routes --advertise-routes=172.18.0.0/16,192.168.1.0/24

Pre-Auth Keys (Automated Setup)

For headless or automated deployments, you can use a pre-authentication key instead of browser login:

Generate a key at login.tailscale.com/admin/settings/keys
Add it to your .env file:
```
TAILSCALE_AUTHKEY=tskey-auth-...
```
The sidecar will automatically connect on startup

Pre-auth keys should be kept secret and rotated regularly. The browser login flow is more secure for interactive setups.

Comparison with Cloudflare

Feature	Tailscale	Cloudflare
Privacy	Private mesh, no public exposure	Public URLs (can be secured with Access)
Setup	One-click browser login	Requires Portal registration
Device Requirement	Tailscale client on each device	Any browser works
Use Case	Personal, private access	Sharing with others, public apps
Cost	Free up to 100 devices	Free tier available

For public access to your apps, use the Cloudflare Gateway instead. You can use both Tailscale and Cloudflare simultaneously.

Next Steps

Install Tailscale on your devices: tailscale.com/download
Learn about exposing apps on your network
Explore Cloudflare Gateway for public access