# Overlay Platform Notes

This document captures prototype release guidance for `geth overlay up`.
Overlay packets are always carried over Iroh on `/geth/overlay/1`; these notes
only cover host interface setup for the local TUN/Wintun-style device.

## Linux

`geth overlay up <name>` uses `tun-rs` to create a layer-3 TUN device and assign
the joined overlay virtual IP.

Operational requirements:

- `/dev/net/tun` must exist and be usable by the daemon process.
- The user service must have enough privilege to create/configure the device,
  commonly `CAP_NET_ADMIN`, a helper, or a supervised manual setup step.
- The daemon should run as a user service; do not install geth as a system
  service just to gain network privileges.

Recovery checks:

- Run `geth overlay interface-plan <name> --platform linux` to inspect the
  intended commands.
- If activation fails, check `/dev/net/tun`, user permissions, and whether the
  service manager strips required capabilities.

## macOS

macOS uses utun-style devices. Release builds must document that host network
integration may require user approval and network-extension or entitlement-aware
packaging depending on the distribution path.

Prototype guidance:

- Run `geth overlay interface-plan <name> --platform macos` before activation.
- Treat `geth overlay up` failures as host entitlement/setup failures, not as a
  reason to fall back to another geth transport.
- Keep the daemon as a LaunchAgent/user service. Do not install a privileged
  system daemon unless a future signed helper design explicitly requires it.

Release checklist:

- Document required entitlements or helper setup for the chosen signing method.
- Document how the LaunchAgent is installed and how users approve networking
  prompts.
- Include this document in release archives.

## Windows

Windows overlay activation needs a Wintun-compatible adapter path. The release
artifact does not silently install kernel drivers.

Prototype guidance:

- Run `geth overlay interface-plan <name> --platform windows` before activation.
- Install or make available Wintun through an operator-approved mechanism before
  `geth overlay up`.
- Keep the daemon as a per-user scheduled task. Do not install geth as a system
  service for the prototype.

Release checklist:

- Either package the Wintun DLL/driver according to its license and installation
  requirements, or clearly point users to an approved Wintun installation path.
- Document how the per-user scheduled task is installed.
- Include this document in release archives.

## Security Boundary

Discovery and peer-card metadata can suggest candidate endpoints and overlay
virtual IPs, but they do not grant access. Packet injection still requires
`overlay.route` on `resource:overlay:<name>`, and joining through a bearer token
must not mutate node identity or grant trust graph permissions.