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 withselectCommandRoute(180.C.25.02): a host reachable over the overlay can satisfylanReachable, so adirect_lanroute 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#
# 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):
{
"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#
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):
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)#
[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)#
[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:
sudo wg-quick up bellona # macOS / Linux
sudo wg show # verify the handshake + transfer counters
Set the host mode:
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, sodirect_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?#
# 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?#
# 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
(
authorizeCommandOverPrivateNetworkechoesevaluatedUnderMode), 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_tunnelwith reasonpolicy-forces-gateway— neverdirect_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:
# 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".