Diff: systems/os-network-admin

From 59d70b8 to 59d70b8

+63 / −39 lines
BeforeAfter
--- ---
schema: foundry-doc-v1 schema: foundry-doc-v1
title: "Fleet control plane" title: "OS Network Admin"
slug: os-network-admin slug: os-network-admin
short_description: "os-network-admin is the control plane for a PointSav Private Network — providing WireGuard mesh routing, the node-join ceremony surface, and Diode-standard enforcement, without holding any archive-tier cryptographic authority."
category: systems category: systems
type: concept type: topic
quality: complete
status: active status: active
audience: vendor-public
bcsc_class: public-disclosure-safe bcsc_class: public-disclosure-safe
language_protocol: PROSE-TOPIC language: en
last_edited: 2026-05-15
editor: pointsav-engineering
paired_with: os-network-admin.es.md paired_with: os-network-admin.es.md
short_description: "os-network-admin is the control plane for a PointSav fleet — one instance per fleet, managing the pairing registry, Diode rules, and mesh routing policy. Commands are composed on an F8 semantic terminal and broadcast as 16-byte binary packets across the WireGuard mesh." last_edited: 2026-05-30
cites: [] editor: editorial
--- ---
`os-network-admin` is the control plane for a PointSav fleet — one instance per deployment, managing the pairing registry, [[diode-standard|Diode]] enforcement rules, and WireGuard mesh routing policy for all [[infrastructure-os|`os-infrastructure`]] nodes in the fleet. Administrators compose commands on an F8 semantic terminal, where plain-language intent is translated locally by [[service-slm|`service-slm`]] into 16-byte binary commands that broadcast across the [[sovereign-mesh|mesh]] simultaneously to every node. There is no central message broker and no third-party service involved in this path. This article covers the control plane's role, the command dispatch architecture, and the relationship between `os-network-admin` and the `os-infrastructure` nodes it governs. `os-network-admin` is the control plane for a PointSav Private Network (PPN). It runs on the network administrator's machine — typically bare metal at the operator's primary site or inside an LXC container on the on-premises fleet node — and provides two functions: a routing and tunnel-integrity substrate for the WireGuard mesh, and an operator approval surface for the node-join ceremony.
## Position in the stack
`os-network-admin` carries the `os-` prefix, marking it as a Foundation layer component — below the application layer, providing system-level services with no user-facing logic of its own. It is a Layer 1 companion to `os-console`, not one of the three archive-tier operating systems (`os-totebox`, `os-console`, `os-orchestration`).
| Component | Layer | Role |
|---|---|---|
| `os-totebox` | Archive tier | Sovereign data vault per entity |
| `os-console` | Archive tier | Keyboard-native operator terminal |
| `os-orchestration` | Archive tier | Multi-archive data aggregator |
| `os-network-admin` | **Foundation** | PPN control plane + ceremony surface |
This distinction matters: `os-network-admin` does not store or process business data. It does not hold archive keys, MBA credentials, or F-key cartridges. It is a blind, secure transport layer for the PPN infrastructure — the entity that manages which physical nodes are authorised on the mesh, not what runs on them.
## What it does
### Routing and tunnel integrity
`os-network-admin` establishes and maintains the WireGuard mesh on the `ppn0` interface. It manages peer-map distribution, monitors tunnel liveness, and enforces the Diode rules that constrain which nodes may send commands to which targets. It does not inspect the content of traffic flowing through the tunnels.
### Node-join ceremony
When a new physical node wants to join the PPN mesh, it generates a Crockford base32 short code (eight characters, approximately 40 bits of entropy). The operator enters this code into `os-network-admin`. A CPace PAKE exchange establishes a shared session key over the short-code channel; a Short Authenticated String (SAS) comparison closes the man-in-the-middle gap. Under this key, the joining node submits its WireGuard public key, receives a cluster CA–signed certificate, and the peer-map distributes automatically.
The current minimal implementation polls the `service-ppn-pairing` backend for pending requests and prints them to stdout. Operator approval is issued via curl:
```bash
PAIRING_SERVER=http://10.8.0.9:9202 ./os-network-admin
# Approve a pending join from another terminal:
curl -s -X POST http://10.8.0.9:9202/v1/node-join/approve \
-H 'Content-Type: application/json' \
-d '{"code":"XXXX-XXXX"}'
```
A full keyboard-driven TUI — with approve/deny keys (`a`/`d`), QR code display via `system-pairing-codes::qr_unicode`, and expiry countdown — is planned as the production operator surface.
## The control plane role ## Relationship to app-network-admin
`os-network-admin` runs one instance per fleet. Its responsibilities are: `app-network-admin` is the F8 Terminal interface that runs on top of `os-network-admin`. It provides two surfaces:
| Function | Description | - **HTTP command surface** at port 8085 — accepts plain-language operator intent, routes it through `service-slm` to produce an authorised command, and dispatches it to the mesh
|---|---| - **UDP mesh broadcast** at port 8090 — sends signed 16-byte binary payloads to PPN peer addresses
| Pairing registry | Maintains the authoritative list of valid `service-pairing` entries across the fleet; issues and revokes hardware-bound [[machine-based-auth|fiduciary tokens]] |
| Diode rule enforcement | Defines which command flows are permitted between fleet members per the [[diode-standard|Diode Standard]]; changes propagate to all nodes via mesh broadcast |
| Mesh routing policy | Manages the WireGuard overlay topology — peer lists, allowed IP ranges, handshake schedules |
| Fleet claims | Accepts incoming [[genesis-protocol|Genesis Protocol]] claim requests from new `os-infrastructure` nodes joining the fleet |
## The F8 terminal and command dispatch The `os-` / `app-` split follows the standard Foundation/Application naming convention: `os-network-admin` is the OS substrate; `app-network-admin` is the operator-facing application that runs on it.
`os-network-admin` operates an F8 terminal — a keyboard-driven semantic input surface. An administrator types plain-language intent; `service-slm` running locally on the same node translates it into a binary command without contacting any external service. ## Relationship to route-network-admin
The dispatch sequence: `route-network-admin` is the deployment instance name for the network admin node in the customer fleet. It is not a separate codebase. A `route-network-admin-1` entry in a fleet manifest means that a physical node at that location is running `os-network-admin` as its primary workload.
1. The administrator types intent at the F8 terminal — for example, instructing the system to isolate a specific edge node. ## Hardware target
2. `service-slm` (running on the same `os-network-admin` node) parses the sentence and produces a two-byte binary command identifying the operation and the target node.
3. `service-udp` broadcasts the 16-byte command packet across the WireGuard mesh on port 8090.
4. Every node in the fleet receives the packet simultaneously. Only the addressed node acts; the others discard.
The translation layer is invisible at the protocol boundary — the mesh sees only the binary command, not the natural-language sentence. The administrator sees only the F8 terminal, not a chat interface. The canonical reference hardware is an iMac 12,1 (Mid-2011) with an Intel Sandy Bridge i5-2400S and a Broadcom 14e4:16b4 NIC. This machine is purpose-suited as a command authority node: it has real hardware VT-x (for running VMs on the same machine if needed), a Broadcom NIC for which `system-substrate-broadcom` provides the silicon detection substrate, and a stable physical location at the operator's site.
## Relationship to os-infrastructure For deployments where bare-metal dedication is impractical, `os-network-admin` can run inside an LXC container on the on-premises fleet node, with the WireGuard interface bridged from the host.
`os-network-admin` and `os-infrastructure` are designed as a pair: ## Zero cryptographic authority
| Layer | Role | `os-network-admin` does not hold F-keys, MBA credentials, or payload capabilities. It cannot read the content of VM-internal state. It cannot approve archive access. Its role is to know which physical nodes are on the mesh and to enforce that membership — nothing more. This architectural constraint is intentional: keeping the network control plane separate from the data plane means a compromise of the routing layer does not yield access to archive contents.
|---|---|
| `os-infrastructure` | Compute substrate — boots on hardware, runs the WireGuard peer, hosts Totebox and other OS instances |
| `os-network-admin` | Control plane — governs the fleet, owns the pairing registry, broadcasts commands |
A minimal fleet is one `os-network-admin` instance and one or more `os-infrastructure` nodes. The control plane does not run on the same node as the compute substrate in production deployments, though a single-machine development configuration is possible. The [[pointsav-private-network|PointSav Private Network]] article describes the WireGuard mesh topology in full. ## Diode discipline
Commands flow downward: `os-network-admin` → `os-infrastructure` (hypervisor layer) → VMs. No VM can issue commands back up to `os-network-admin`. No archive can instruct the mesh to add or remove a node. This unidirectional discipline is the same Diode standard that governs the archive tier (`os-console` → `os-orchestration` → `os-totebox`).
## See also ## See also
- [[infrastructure-os]] — the compute substrate nodes that `os-network-admin` governs - [[sovereign-mesh]] — the WireGuard overlay and 16-byte binary command protocol
- [[os-family-overview]] — the eight-OS family and how each member fits - [[genesis-protocol]] — the autonomous bootstrap sequence that `os-network-admin` executes on a fresh node
- [[diode-standard]] — the protocol governing unidirectional command flow across the fleet - [[machine-based-auth]] — the MBA pairing model that governs archive-tier access
- [[service-slm]] — the local semantic language model that translates commands - [[infrastructure-os]] — the Type I hypervisor layer that `os-network-admin` manages
- [[machine-based-auth]] — the fiduciary keypairs and pairing registry `os-network-admin` manages - [[diode-standard]] — the authority hierarchy and traffic rules the control plane enforces
- [[deployment-patterns]] — the six canonical fleet configurations