Networking Overview #
The Substrate binds all ports to 127.0.0.1 by default — nothing is exposed to the network. This is intentional: the API key auth is designed for local use, and exposing ports directly to the internet is discouraged.
For remote access (e.g., connecting your Aether OS frontend to a Substrate running on a home server or VPS), use a secure tunnel.
If you installed Substrate with the recommended CLI workflow, use these first:
# Public HTTPS with a custom hostname
aether-substrate tunnel cloudflare --hostname substrate.example.com
# Private access across your tailnet
aether-substrate tunnel tailscale
The rest of this document covers the lower-level manual setup behind those commands.
Whether you start the stack with the CLI or with docker compose, local verification is the same: docker compose ps or Docker Desktop should show aether-substrate and aether-caddy, plus aetheros-user-workspace if workspace support is enabled.
Options at a Glance #
| Method | Pros | Cons | When to use |
|---|---|---|---|
| Cloudflare Tunnel | Free, automatic HTTPS, custom domains, zero open ports, survives IP changes | Requires Cloudflare account, traffic routes through CF edge | Always-on remote access, custom domains |
| Tailscale | Private mesh, no config, MagicDNS, ACLs, team sharing | Requires Tailscale on both ends, no custom public domains | Team/personal private access |
| Caddy (built-in) | Already configured, internal TLS | Self-signed cert (browsers warn), LAN only | Local dev, same-machine access |
| SSH Tunnel | Zero setup, uses existing SSH | Manual, per-session, no auto-reconnect | Quick ad-hoc access |
Quick Comparison #
Cloudflare Tunnel (cloudflared) #
Best for: persistent HTTPS access with a custom domain, no open firewall ports.
The tunnel connects outbound from your server to Cloudflare's edge. Clients connect to your domain via Cloudflare. No ports need to be open on your server/router.
- Free tier available (unlimited tunnels)
- Automatic TLS certificates
- Works behind NAT, CGNAT, firewalls
- Survives IP changes, ISP reboots, overnight cert expiry
- Supports WebSocket (required for terminal/firehose)
Tailscale #
Best for: private access across devices without exposing anything to the public internet.
Tailscale creates a WireGuard mesh VPN between your devices. Your Substrate gets a stable IP (100.x.x.x) and optional MagicDNS hostname accessible from any device on your tailnet.
- No ports exposed publicly
- Automatic key rotation and NAT traversal
- Share access with team members via ACLs
- HTTPS via Tailscale certs (
tailscale cert) - Works on all platforms including mobile
SSH Tunnel (ad-hoc) #
For quick one-off access without installing anything:
# From your laptop, forward local:3100 to the remote Substrate
ssh -L 3100:127.0.0.1:3100 user@your-server
# Now access Substrate at http://localhost:3100 on your laptop
For WebSocket support (terminal, firehose), you'll also want to forward the Caddy port:
ssh -L 3100:127.0.0.1:3100 -L 8443:127.0.0.1:8443 user@your-server
This is session-based and manual — use Cloudflare Tunnel or Tailscale for persistent access.
Configuring the Aether OS Frontend #
Once your tunnel is running, point the frontend at your Substrate URL:
# In your Aether OS .env (or .env.local)
NEXT_PUBLIC_SUBSTRATE_URL=https://substrate.yourdomain.com
# or for Tailscale:
NEXT_PUBLIC_SUBSTRATE_URL=https://your-machine.tail1234.ts.net:3100
The SUBSTRATE_API_KEY is sent in the x-substrate-key header — ensure it matches between your frontend env and the Substrate's .env.
CORS #
When connecting from a different origin, add it to the Substrate's allowed origins:
# In substrate .env
SUBSTRATE_ALLOWED_ORIGINS=https://aetheros.computer,https://your-custom-domain.com
Security Notes #
- Never expose port 3100 directly to the internet without a tunnel or VPN
- The API key provides authentication but not encryption — always use HTTPS (Caddy, cloudflared, or Tailscale certs)
- WebSocket connections are authenticated on the initial handshake via the API key
- Cloudflare Tunnel and Tailscale both provide encryption in transit