tractor/examples/multihost/wg_lan

tractor over a WireGuard tunnel, declared as one maddr

A two-host LAN setup: a tractor actor tree on host A, dialed from host B, with the endpoint declared as a single wg multiaddr.

Supersedes the example set in gh #482 — see what changed.

Why examples/multihost/? tests/test_docs_examples.py walks examples/ recursively and runs everything it collects as a subproc, asserting rc == 0. These need a real second host and a live wg tunnel, so they can’t satisfy that; 'multihost' not in p[0] is already in the test’s exclusion list, which is what keeps them out of CI.

the maddr form

/ip4/192.168.1.50/udp/51820/wg/u<A_pub>/ip4/10.0.11.1/tcp/1616
\____ wg bearer ___________/\__ key __/\____ tractor ep _____/
 underlay, wg `ListenPort`              overlay, on the wg iface
 (kernel/`wg(8)` owns it)               (the ONLY part tractor binds)

Three parts, three different owners:

part	who binds it	in the runtime?
/ip4/../udp/51820 bearer	kernel via wg-quick/pyroute2	no
/wg/u<key>	nothing — it’s an identity	no, verified out-of-band
/ip4/../tcp/1616 overlay	tractor’s IPCServer	yes, as .overlay

Verified against py-multiaddr #108: this composed form parses and round-trips (['ip4','udp','wg','ip4','tcp']).

requirements

py-multiaddr #108 is merged (2026-07-28) but ships in no release yet — the latest 0.2.0 (2026-03-17) predates it and has no wg codec. So pyproject.toml carries a temporary [tool.uv.sources] rev pin at the merge commit, and a plain

uv sync

gets you a wg-aware multiaddr. That pin goes away once a release carries the codec. You also need multibase:

uv pip install multibase

Without the codec parse_wg_maddr() raises immediately with an actionable message — there is deliberately no degraded hand-split fallback. _have_wg_maddr_proto() is the predicate.

Every peel and re-compose here goes through py-multiaddr’s own tunnel API (.decapsulate_code(), .split(), .join(), .encapsulate(), .value_for_protocol()) rather than any bespoke segment slicing — see its README “En/decapsulate” and “Tunneling” sections. gh #429 was about dropping our NIH parser, and that applies to peeling a tunnel stack just as much as to decoding one proto.

0. tunnel setup (out-of-band, both hosts)

Host A is the service host (underlay e.g. 192.168.1.50), host B your workstation. Overlay net 10.0.11.0/24.

umask 077
wg genkey | tee wg_priv.key | wg pubkey > wg_pub.key

/etc/wireguard/wg0.conf on host A:

[Interface]
PrivateKey = <A_priv>
Address = 10.0.11.1/24
ListenPort = 51820

[Peer]
PublicKey = <B_pub>
AllowedIPs = 10.0.11.2/32

on host B:

[Interface]
PrivateKey = <B_priv>
Address = 10.0.11.2/24

[Peer]
PublicKey = <A_pub>
Endpoint = 192.168.1.50:51820
AllowedIPs = 10.0.11.1/32
PersistentKeepalive = 25

Note how ListenPort and Endpoint are exactly the maddr’s bearer segment, and [Interface] Address is its overlay host.

sudo wg-quick up wg0   # both hosts
ping -c1 10.0.11.1     # from B

1. get your pubkey into the maddr

python -c "
import base64, multibase
key = open('wg_pub.key').read().strip()
print(multibase.encode('base64url', base64.b64decode(key)).decode())
"

Paste the u... output into WG_MADDR in both scripts (they use the same string — A’s bearer, A’s key, A’s overlay ep).

2. run

# host A
python host_a_srv.py

# host B
python host_b_client.py

host_a_srv.py must be importable on host B too, since portal.run() refs the fn by module path — standard tractor RPC semantics.

what changed vs #482

Four corrections, all from ai/tpt-backends/03_wg_tunnel_bindspace.md:

1. the maddr semantics were inverted. #482 used /ip4/10.0.11.1/tcp/1616/wg/u<key> — that parses, but it puts the overlay addr where the bearer belongs and tcp where wg’s udp ListenPort goes, and it declares no overlay ep at all. parse_wg_maddr() now rejects it with an actionable error.
2. parsing is pure. #482’s helper had the key-check adjacent to the parse; verify_wg_peer() is now a separate, explicitly composed step that the caller invokes. A parser that shells out is a nasty surprise.
3. no sudo. #482 ran sudo wg show; a library/example must never escalate. wg show works unprivileged for read on most setups; if yours needs root, run the script as root rather than embedding sudo.
4. no new Address proto-type. The tunnel rides beside the overlay addr in a frozen WGTunnelledAddr, and only .overlay crosses into open_nursery(). #482 §6 floated a WGAddress registered in _address_types — that table is a bidict (1:1 proto-key↔︎type) and _addr_to_transport wants a MsgTransport per addr-type, which wg doesn’t have.

next

WGTunnelledAddr is deliberately example-local. Promoting it to tractor.discovery as a TunnelledAddress whose .proto_key/.unwrap() delegate to .overlay, plus open_bindspace() @acms that create/tear down the iface + netns via pyroute2, is layers A→C of the plan doc.