aether-substrate docs tailscale.md
6.5 kB · 246 lines
Markdown
at main

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.

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 #

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.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:

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/tun is available
  • Check TS_AUTHKEY is valid and not expired
  • Verify NET_ADMIN capability 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.