# 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: ```bash # 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) **[Full guide: cloudflared.md](cloudflared.md)** ### 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 **[Full guide: tailscale.md](tailscale.md)** ### SSH Tunnel (ad-hoc) For quick one-off access without installing anything: ```bash # 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: ```bash 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: ```bash # 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: ```bash # 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