# 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: ```bash # 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](https://tailscale.com/) (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 ```bash # macOS brew install tailscale # Linux (Debian/Ubuntu) curl -fsSL https://tailscale.com/install.sh | sh # Other: https://tailscale.com/download ``` #### 2. Connect ```bash 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): ```yaml # 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.0` exposes ports on all interfaces. If your machine is also on a public network, use `tailscale ip -4` to get your Tailscale IP and bind specifically to that. #### 4. Access from Another Device From any device on your tailnet: ```bash 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`: ```yaml 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](https://login.tailscale.com/admin/settings/keys) and add it to your `.env`: ```bash TS_AUTHKEY=tskey-auth-xxxxx ``` ### Option C: Tailscale Serve (HTTPS) Tailscale can issue real HTTPS certificates for your machine's MagicDNS name: ```bash # 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](https://login.tailscale.com/admin/dns) if it's not already on. ## Frontend Configuration ```bash # 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: ```bash # 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](https://tailscale.com/kb/1018/acls): ```json { "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: ```bash 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): ```bash 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 ```bash # 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/tun` is available - Check `TS_AUTHKEY` is valid and not expired - Verify `NET_ADMIN` capability is set ### MagicDNS not resolving ```bash # 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.