Overlay and relays

AIOE reaches workbenches in two ways. The relay is always on: every enrolled workbench keeps an outbound HTTPS connection to the API, and remote control travels down it. The overlay is optional: a private WireGuard network between your workbenches, nodes and the platform, which carries remote control end to end encrypted between machines and makes screen mirroring possible. Neither needs an inbound port on any workbench.

The relayCopy Anchor Link

A workbench holds one Server-Sent Events stream open to /relay/v1/workbench/stream. When someone controls it from the console or the mobile app, the API writes the request to that stream, and the workbench answers on /relay/v1/workbench/respond. The workbench checks every request against the scopes it was granted and against its policy, and records it in its own audit trail under the real person.

There is nothing to deploy for the relay: it is part of the API. What it needs:

• Proxies and load balancers in front of the API must not buffer responses and must allow long reads. See Install with Helm.
• With more than one API replica, Redis, so a request reaching one replica finds a workbench connected to another. See Redis for more than one replica.
• A request waits AIOE_RPC_TIMEOUT seconds (default 30) for the workbench to answer.

Who may control a workbench: the person who enrolled it, operators and administrators. What they may do is what was granted when it was approved (by default everything except viewing and controlling the screen), narrowed again by the organisation's policy ("Remote Control" in Policy).

The overlayCopy Anchor Link

Each organisation gets its own private address range, a /16 inside 100.64.0.0/10, allocated the first time a node joins. A node makes its own WireGuard key pair, registers only the public key, and receives an address, the peers it may reach, and how to reach them. The private key never leaves the machine, and a node ignores any address outside your range.

Who reaches whom is decided by the mesh policy on the console's Mesh page: owners reach their own nodes, operators and administrators reach every node, and tag rules connect groups (for example, nodes tagged dev may reach nodes tagged build). Disabled nodes drop out of every map.

How traffic flows: nodes try each other's addresses directly first, found through STUN and on the local network, which works across most NATs. Where there is no direct path (symmetric NATs, networks that block UDP, hosts that accept only HTTPS) WireGuard packets go through the mesh relay over HTTPS. The mesh relay only ever sees encrypted packets, a node proves it owns its key before it may use it, and packets never cross organisations.

Remote control over the overlay: when a workbench is on the overlay, the API sends remote control through the gateway, signed with the platform's key so the workbench can tell the platform from any other node, and falls back to the relay if that fails. The console marks each call "via mesh" or "via relay". Viewing a workbench's screen works only over the overlay.

Add the overlay on AzureCopy Anchor Link

Deploy with deployMesh=true. The template adds two apps from the aioe-mesh-services image (put it in the registry with the others, tagged meshImageTag):

• aioe-<env>-relay: the mesh relay, public HTTPS, one replica;
• aioe-<env>-gateway: the gateway, reachable only inside the environment.

Pass gatewaySecret (a long random string, for example openssl rand -base64 32) and signingKey with the deployment. The template points the API at both, and lists two relays for nodes: the API's own host first (the API passes /relay/v1/mesh through to the relay app, so a network that allows only your API's host name still works), then the relay app's own host name.

Add the overlay elsewhereCopy Anchor Link

The Helm chart does not include the overlay services. Run the aioe-mesh-services image twice, with different commands:

The gateway's token file holds aioe_gw_<tenant>.<secret>, where <tenant> is your AIOE_BOOTSTRAP_TENANT and <secret> is the gateway secret. Then set these on the API:

[
  { "id": "api", "region": "syd", "host": "https://aioe.example.com/relay/v1/mesh", "port": 443 },
  { "id": "syd", "region": "syd", "host": "relay.aioe.example.com", "port": 443 }
]

When both gateway values are set, the API logs remote control: mesh first, relay fallback; otherwise remote control: relay only.

What nodes need from the networkCopy Anchor Link

The agent honours HTTPS_PROXY, HTTP_PROXY and NO_PROXY, including a Basic user name and password in the proxy address. Windows integrated proxy sign-in (Negotiate or NTLM) is not supported: put a Basic credential in the proxy address, or allow the platform's host without authentication. Behind a proxy that inspects TLS, give the agent your proxy's CA with --ca-file (or AIOE_CA_FILE).

Other overlay settings (MTU 1280, map refresh every 30 s, keepalive 25 s, offline after 120 s) are in Environment variables.

The overlay agentCopy Anchor Link

aioe-mesh is a single program for Linux, Windows and macOS that puts a machine on the overlay. It runs WireGuard in user space: it needs no administrator rights, no network interface and no routes, and only the ports it is told to expose accept connections from the overlay. AI Workbench and headless nodes run it for you.

Exit code 3 means the platform rejected the token: sign in again before restarting. The agent keeps its key and status in ~/.local/state/aioe-mesh on Linux and macOS (or $XDG_STATE_HOME/aioe-mesh), and %LOCALAPPDATA%\MojoUp\aioe-mesh on Windows.