Eve library

Tailscale / WireGuard Private-Network Mode (Optional)

Guide

Revision 1

On this page

Status: Phase 180.C.25.10 implementation.

This document covers Bellona Remote Control's optional private-network mode: running the operator machine and the host MacBook on the same Tailscale tailnet (or a WireGuard mesh) so the host is reachable over a private, end-to-end encrypted overlay even when the two are not on the same physical LAN.

The one rule that matters: the tailnet is a transport, not a trust anchor. Being on the overlay does not authenticate a device and does not replace the gateway's device-token authentication or command policy. Every command is still gated by the host token + policy exactly as it is over the public gateway. See Trust Boundary.

Code#

The mode is implemented in apps/bellona/remote-host/src/private-network.ts:

  • RemotePrivateNetworkMode — tailscale | wireguard | none.
  • createRemotePrivateNetworkConfig({ mode }) — the config (mode + treatTailnetAsLan + overlay CIDRs).
  • selectCommandRouteWithPrivateNetwork(...) — composes with selectCommandRoute (180.C.25.02): a host reachable over the overlay can satisfy lanReachable, so a direct_lan route can be taken over the tailnet instead of always tunnelling through the cloud gateway.
  • authorizeCommandOverPrivateNetwork(...) — the literal auth/policy gate that runs before dispatch, independent of the network path. It can never be satisfied by the overlay; an unauthenticated device on the tailnet is rejected.

Tests in apps/bellona/remote-host/src/private-network.test.ts prove both the routing composition and the boundary (an unauthenticated device on the tailnet is rejected; a high-risk command is still forced through the audited gateway).

When To Use This#

Use the private-network mode when:

  • You want lower latency than the cloud gateway for direct_lan-eligible commands but the operator and host are not on the same physical LAN (e.g. home
    • studio, or two networks behind different NATs).
  • You want the host reachable without exposing any inbound port to the public internet (the host still makes only outbound connections to the overlay coordination server / peers).

Do not use it as a security control. It reduces the network attack surface, but Bellona's authorization is unchanged by it.

Tailscale Setup#

Tailscale is a managed WireGuard overlay. Install it on both the operator machine and the host MacBook and join the same tailnet.

Host MacBook#

sh
# Install (Homebrew or the signed pkg from tailscale.com/download).
brew install --cask tailscale

# Bring the node up. Use an ephemeral, tagged auth key from the Tailscale admin
# console (Settings → Keys) so the host is least-privileged on the tailnet.
sudo tailscale up \
  --hostname=bellona-host-studio \
  --accept-routes=false \
  --advertise-tags=tag:bellona-host

# Confirm the node's tailnet address (100.x.y.z / CGNAT range).
tailscale ip -4
tailscale status

Lock the tailnet down with a Tailscale ACL so only the operator node can reach the host node, and only on the Bellona host port. Example ACL fragment (Tailscale admin console → Access Controls):

jsonc
{
  "tagOwners": {
    "tag:bellona-host": ["autogroup:admin"],
    "tag:bellona-operator": ["autogroup:admin"]
  },
  "acls": [
    {
      // Only the operator tag may reach the host tag, only on the host's
      // direct-LAN listener port. Everything else on the tailnet is denied.
      "action": "accept",
      "src": ["tag:bellona-operator"],
      "dst": ["tag:bellona-host:7443"]
    }
  ]
}

The ACL restricts reachability. It is defence-in-depth, not a substitute for Bellona auth: a node that matches the ACL still has to pass the host-token + policy gate.

Operator Machine#

sh
sudo tailscale up --hostname=bellona-operator --advertise-tags=tag:bellona-operator
tailscale status   # confirm the host node is visible

Wire It Into The Host#

Set the host's private-network mode (config surface — see apps/bellona/remote-host/src/private-network.ts):

env
BELLONA_REMOTE_HOST_PRIVATE_NETWORK_MODE=tailscale

Point the operator's direct-LAN discovery at the host's tailnet address/hostname (MagicDNS gives you bellona-host-studio as a name). The host token + cert fingerprint verification used for any direct-LAN session are unchanged.

WireGuard Setup (Self-Hosted)#

If you prefer a self-hosted mesh, use plain WireGuard. Generate a key pair on each peer and configure a point-to-point tunnel.

Host MacBook (/usr/local/etc/wireguard/bellona.conf)#

ini
[Interface]
# Host's private overlay address inside the Bellona WireGuard range.
Address = 10.97.0.2/32
PrivateKey = <host-private-key>
ListenPort = 51820

[Peer]
# The operator machine.
PublicKey = <operator-public-key>
AllowedIPs = 10.97.0.1/32
# If the operator is behind NAT, the host dials out to a known endpoint or a
# relay; otherwise the operator initiates.
PersistentKeepalive = 25

Operator Machine (bellona.conf)#

ini
[Interface]
Address = 10.97.0.1/32
PrivateKey = <operator-private-key>

[Peer]
PublicKey = <host-public-key>
Endpoint = <host-reachable-endpoint>:51820
AllowedIPs = 10.97.0.2/32
PersistentKeepalive = 25

Bring the tunnels up:

sh
sudo wg-quick up bellona      # macOS / Linux
sudo wg show                  # verify the handshake + transfer counters

Set the host mode:

env
BELLONA_REMOTE_HOST_PRIVATE_NETWORK_MODE=wireguard

AllowedIPs is the WireGuard equivalent of the Tailscale ACL: keep it to the single peer address, never 0.0.0.0/0, so the overlay only carries operator↔host traffic.

Trust Boundary#

This is the part you must not get wrong.

Property On the public gateway On the tailnet / WireGuard
Network path Cloud gateway tunnel Private encrypted overlay
Host-token authentication Required Required (unchanged)
Device must be registered Required Required (unchanged)
Cert-fingerprint host verification (for direct_lan) Required Required (unchanged)
Command policy / risk gate Enforced Enforced (unchanged)
Audit of high-risk commands Forced to gateway Still forced to gateway

What the private-network mode does:

  • Lets a host reachable over the overlay satisfy lanReachable, so direct_lan-eligible commands can take the lower-latency private path (selectCommandRouteWithPrivateNetwork).

What it does not do — ever:

  • It does not set lanVerified. An unverified host (no cert-fingerprint match) is still routed to the gateway, tailnet or not.
  • It does not authenticate a device. A node that can reach the host over WireGuard but cannot present a valid gateway-issued host token is rejected (authorizeCommandOverPrivateNetwork → device-not-authenticated).
  • It does not grant any permission, and it does not lift the policy gate. A high-risk command is still forced through the audited gateway path even when a verified host is reachable over the tailnet (policy-forces-gateway).
  • It does not let a blocked or unregistered device act.

In short: the overlay can change where the bytes go; it cannot change who is allowed to send them.

Diagnostics#

1. Is the overlay actually up?#

sh
# Tailscale
tailscale status            # both nodes "active"; note the host's 100.x address
tailscale ping bellona-host-studio   # direct vs DERP-relayed path

# WireGuard
sudo wg show                # look for a recent "latest handshake" + rising transfer
ping 10.97.0.2              # host overlay address answers

2. Is the host reachable on its Bellona port over the overlay?#

sh
# Replace with the host's overlay address + direct-LAN port (default 7443).
nc -vz bellona-host-studio 7443        # Tailscale MagicDNS name
nc -vz 10.97.0.2 7443                  # WireGuard address

If the port is closed, the overlay is up but the host listener or the Tailscale ACL / WireGuard AllowedIPs is blocking it — fix reachability before expecting a direct_lan route.

3. Verify policy STILL gates (the important one)#

The overlay must never let an unauthenticated or policy-denied command through. Confirm with the host's own logs/timeline, not with connectivity:

  • Send a command from an operator that is on the tailnet but not paired / whose host token is absent or expired. The gateway/host must reject it. The audit entry records the denial with the device id and the active mode (authorizeCommandOverPrivateNetwork echoes evaluatedUnderMode), proving the same gate ran on the tailnet.
  • Send a high-risk command from a verified, tailnet-reachable host. It must still be routed gateway_tunnel with reason policy-forces-gateway — never direct_lan.

If either of those succeeds on the tailnet but would have been denied over the gateway, that is a critical bug: stop and file it. The whole point of this mode is that the answer is identical on both paths.

4. Confirm no inbound public exposure was opened#

The private-network mode requires no inbound public port. Verify the host still only listens on loopback + the overlay interface:

sh
# macOS — the Bellona direct-LAN listener should bind the overlay/LAN address,
# never 0.0.0.0 on a public interface.
sudo lsof -nP -iTCP -sTCP:LISTEN | grep -i bellona

Explicit Guidance#

Tailscale/WireGuard private-network mode does NOT replace gateway authentication or policy. It is a transport convenience that lowers latency and removes the need for public inbound exposure. Device-token authentication, device registration, cert-fingerprint host verification, and the command policy gate apply in full on every command regardless of whether it arrived over the public gateway or the private overlay. Do not treat tailnet membership as authorization, and do not relax any Bellona control because "we're on the tailnet".