Tailscale #
Access your Substrate privately over a WireGuard mesh VPN — no ports exposed to the public internet, automatic NAT traversal, and stable IPs across devices.
CLI Route (Recommended) #
If you installed Substrate with the aether-substrate CLI, use the CLI flow first:
# During first-time bootstrap
aether-substrate init --tunnel tailscale
# Or after Substrate is already configured
aether-substrate tunnel tailscale
The manual options below describe the lower-level setup behind that workflow.
Once the stack is running, docker compose ps or Docker Desktop should still show the same local services: aether-substrate and aether-caddy, plus aetheros-user-workspace if workspace support is enabled.
Prerequisites #
- A Tailscale account (free for personal use, up to 100 devices)
- Tailscale installed on the machine running your Substrate
- Tailscale installed on any device you want to connect from
Setup #
Option A: Tailscale on the Host (Recommended) #
The simplest approach — install Tailscale on the host machine and access the Substrate at the host's Tailscale IP.
1. Install Tailscale #
# macOS
brew install tailscale
# Linux (Debian/Ubuntu)
curl -fsSL https://tailscale.com/install.sh | sh
# Other: https://tailscale.com/download
2. Connect #
sudo tailscale up
# Note your Tailscale IP
tailscale ip -4
# e.g., 100.64.0.1
3. Update Substrate to Listen on Tailscale #
By default, the Substrate binds to 127.0.0.1. To make it accessible over Tailscale, update docker-compose.yml to bind to the Tailscale IP or 0.0.0.0 (safe since Tailscale handles access control):
# In docker-compose.yml, change port bindings:
ports:
- "0.0.0.0:3100:3100" # or use your Tailscale IP
- "0.0.0.0:2580:2480"
Security note: Binding to
0.0.0.0exposes ports on all interfaces. If your machine is also on a public network, usetailscale ip -4to get your Tailscale IP and bind specifically to that.
4. Access from Another Device #
From any device on your tailnet:
curl http://100.64.0.1:3100/health
Option B: Tailscale in a Sidecar Container #
Run Tailscale as a Docker container alongside the Substrate. Useful when you can't or don't want to install Tailscale on the host.
Add to your docker-compose.yml:
services:
tailscale:
image: tailscale/tailscale:latest
container_name: aether-tailscale
hostname: aether-substrate # This becomes the MagicDNS name
cap_add:
- NET_ADMIN
- SYS_MODULE
volumes:
- tailscale-state:/var/lib/tailscale
- /dev/net/tun:/dev/net/tun
environment:
- TS_AUTHKEY=${TS_AUTHKEY} # Pre-auth key from Tailscale admin
- TS_STATE_DIR=/var/lib/tailscale
- TS_EXTRA_ARGS=--advertise-tags=tag:substrate
networks:
- internal
restart: unless-stopped
volumes:
tailscale-state:
driver: local
Generate a pre-auth key at Tailscale Admin > Settings > Keys and add it to your .env:
TS_AUTHKEY=tskey-auth-xxxxx
Option C: Tailscale Serve (HTTPS) #
Tailscale can issue real HTTPS certificates for your machine's MagicDNS name:
# Enable HTTPS certificates
tailscale cert aether-substrate.tail1234.ts.net
# Serve the Substrate API over HTTPS
tailscale serve https / http://127.0.0.1:3100
# Check status
tailscale serve status
This gives you a valid HTTPS URL like https://aether-substrate.tail1234.ts.net accessible from any device on your tailnet — with a real TLS certificate, no browser warnings.
MagicDNS #
With MagicDNS enabled (on by default), devices on your tailnet get human-readable names:
http://aether-substrate:3100/health
# or with the full domain:
http://aether-substrate.tail1234.ts.net:3100/health
Enable MagicDNS in the Tailscale admin console if it's not already on.
Frontend Configuration #
# In your Aether OS .env.local
# Using Tailscale IP:
NEXT_PUBLIC_SUBSTRATE_URL=http://100.64.0.1:3100
# Using MagicDNS:
NEXT_PUBLIC_SUBSTRATE_URL=http://aether-substrate:3100
# Using Tailscale Serve (HTTPS):
NEXT_PUBLIC_SUBSTRATE_URL=https://aether-substrate.tail1234.ts.net
SUBSTRATE_API_KEY=your-key-here
Don't forget to add the origin to CORS if it differs from the defaults:
# In substrate .env
SUBSTRATE_ALLOWED_ORIGINS=http://100.64.0.1:4305,http://aether-substrate:4305
Access Control (ACLs) #
Restrict who on your tailnet can access the Substrate using Tailscale ACLs:
{
"acls": [
{
"action": "accept",
"src": ["group:developers"],
"dst": ["tag:substrate:3100"]
}
],
"tagOwners": {
"tag:substrate": ["autogroup:admin"]
}
}
Sharing with Others #
Share a device #
Temporarily share your Substrate with someone who has Tailscale but isn't on your tailnet:
tailscale share aether-substrate user@example.com
Funnel (Public Access) #
If you want to expose the Substrate to the public internet via Tailscale (instead of Cloudflare):
tailscale funnel 3100
This creates a public URL like https://aether-substrate.tail1234.ts.net — similar to Cloudflare Tunnel but routed through Tailscale's infrastructure.
Troubleshooting #
Can't reach Substrate from another device #
# Verify both devices are on the tailnet
tailscale status
# Check if the Substrate host is reachable
tailscale ping aether-substrate
# Verify port is listening
curl http://100.64.0.1:3100/health
Docker container can't join tailnet #
- Ensure
/dev/net/tunis available - Check
TS_AUTHKEYis valid and not expired - Verify
NET_ADMINcapability is set
MagicDNS not resolving #
# Check MagicDNS status
tailscale dns status
# Fall back to IP
tailscale ip -4
Cloudflare Tunnel vs Tailscale #
| Cloudflare Tunnel | Tailscale | |
|---|---|---|
| Access | Public (anyone with the URL) | Private (tailnet members only) |
| Custom domain | Yes | MagicDNS only (or Funnel for public) |
| HTTPS | Automatic (Cloudflare certs) | Via tailscale cert or Serve |
| Install required on clients | No | Yes |
| Best for | Public/semi-public access | Private/team access |
Use Cloudflare Tunnel when you need a public URL or custom domain. Use Tailscale when access should be private to your devices or team.