Diff: architecture/ppn-architecture-overview
From 1c02ec1 to 1c02ec1
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "PPN Architecture Overview" | title: "PPN Architecture Overview" |
| slug: ppn-architecture-overview | slug: ppn-architecture-overview |
| short_description: "The PointSav Private Network (PPN) is the physical infrastructure plane of the PointSav stack — responsible for enrolling physical nodes into a cryptographically authenticated mesh, managing the compute resources those nodes provide, and hosting the virtual machines that run Totebox Archives and orchestration gateways." | short_description: "The PointSav Private Network (PPN) is the physical infrastructure plane of the PointSav stack — responsible for enrolling physical nodes into a cryptographically authenticated mesh, managing the compute resources those nodes provide, and hosting the virtual machines that run Totebox Archives and orchestration gateways." |
| category: architecture | category: architecture |
| type: topic | type: topic |
| content_type: topic | content_type: topic |
| status: active | status: active |
| bcsc_class: public-disclosure-safe | bcsc_class: public-disclosure-safe |
| language: en | language: en |
| paired_with: ppn-architecture-overview.es.md | paired_with: ppn-architecture-overview.es.md |
| last_edited: 2026-05-30 | last_edited: 2026-05-30 |
| editor: editorial | editor: editorial |
| --- | --- |
| The **PointSav Private Network (PPN)** is the physical infrastructure plane of the PointSav stack. It is the layer responsible for: enrolling physical nodes into a cryptographically authenticated mesh, managing the compute resources those nodes provide, and hosting the virtual machines that run Totebox Archives and orchestration gateways. The PPN is not a data access layer. It does not hold data. It does not make authentication decisions about who may read an archive. It manages physical infrastructure so that the data layer can run on top of it. | The **PointSav Private Network (PPN)** is the physical infrastructure plane of the PointSav stack. It is the layer responsible for: enrolling physical nodes into a cryptographically authenticated mesh, managing the compute resources those nodes provide, and hosting the virtual machines that run Totebox Archives and orchestration gateways. The PPN is not a data access layer. It does not hold data. It does not make authentication decisions about who may read an archive. It manages physical infrastructure so that the data layer can run on top of it. |
| ## The four layers | ## The four layers |
| The PPN and the systems built on top of it are organised into four layers. Each layer is blind to the internal state of the layers below and above it. | The PPN and the systems built on top of it are organised into four layers. Each layer is blind to the internal state of the layers below and above it. |
| ### Operator layer | ### Operator layer |
| The operator layer is where a human administrator interacts with the fleet. | The operator layer is where a human administrator interacts with the fleet. |
| **`os-network-admin`** is the Foundation OS layer — the control plane for the PPN mesh. It runs on the operator's machine (bare metal or LXC container), manages peer-map distribution, and enforces the Diode rules that restrict command flow. It holds zero cryptographic authority: it cannot read archive data, it cannot approve data access, and it cannot issue identity credentials. Its role is to know which physical nodes are on the mesh and to enforce that membership — nothing more. | **`os-network-admin`** is the Foundation OS layer — the control plane for the PPN mesh. It runs on the operator's machine (bare metal or LXC container), manages peer-map distribution, and enforces the Diode rules that restrict command flow. It holds zero cryptographic authority: it cannot read archive data, it cannot approve data access, and it cannot issue identity credentials. Its role is to know which physical nodes are on the mesh and to enforce that membership — nothing more. |
| **`app-network-admin`** is the F8 Terminal interface that runs on top of `os-network-admin`. It accepts plain-language operator intent at HTTP port 8085, routes it through `service-slm` to produce an authorised 16-byte binary command, and broadcasts that command over UDP port 8090 to the mesh. | **`app-network-admin`** is the F8 Terminal interface that runs on top of `os-network-admin`. It accepts plain-language operator intent at HTTP port 8085, routes it through `service-slm` to produce an authorised 16-byte binary command, and broadcasts that command over UDP port 8090 to the mesh. |
| See: [[os-network-admin]], [[ppn-command-protocol]] | See: [[os-network-admin]], [[ppn-command-protocol]] |
| ### PPN layer | ### PPN layer |
| The PPN layer is the physical transport and ceremony substrate. | The PPN layer is the physical transport and ceremony substrate. |
| The **[[sovereign-mesh]]** is a WireGuard cryptographic overlay on a dedicated `ppn0` interface. Every node in the fleet holds a long-term keypair; every packet is encrypted before leaving the node. Commands travel as 16-byte binary packets broadcast simultaneously to all mesh peers; only the addressed node acts. | The **[[sovereign-mesh]]** is a WireGuard cryptographic overlay on a dedicated `ppn0` interface. Every node in the fleet holds a long-term keypair; every packet is encrypted before leaving the node. Commands travel as 16-byte binary packets broadcast simultaneously to all mesh peers; only the addressed node acts. |
| **`service-ppn-pairing`** is the ceremony backend that manages node-join requests. When a new physical node wants to join the mesh, it generates a Crockford base32 short code (~40 bits of entropy). The operator enters this code; a CPace PAKE exchange establishes a shared session key; a Short Authenticated String (SAS) comparison closes the man-in-the-middle gap. The approved node is written to the `nodes.jsonl` append-only registry. | **`service-ppn-pairing`** is the ceremony backend that manages node-join requests. When a new physical node wants to join the mesh, it generates a Crockford base32 short code (~40 bits of entropy). The operator enters this code; a CPace PAKE exchange establishes a shared session key; a Short Authenticated String (SAS) comparison closes the man-in-the-middle gap. The approved node is written to the `nodes.jsonl` append-only registry. |
| The **[[genesis-protocol]]** governs first boot: a node generates its keypair from hardware entropy, enters a sealed holding pattern, and awaits an administrative claim — without any pre-provisioning or control-plane dependency. | The **[[genesis-protocol]]** governs first boot: a node generates its keypair from hardware entropy, enters a sealed holding pattern, and awaits an administrative claim — without any pre-provisioning or control-plane dependency. |
| ### Hypervisor layer | ### Hypervisor layer |
| The hypervisor layer is the compute substrate. | The hypervisor layer is the compute substrate. |
| **`os-infrastructure`** is the Type I hypervisor that hosts the virtual machines running Totebox Archives and orchestration gateways. It manages a **per-node resource pool**: memory via `virtio_balloon` (inflation reclaims guest RAM into the node pool; deflation returns it) and CPU via cgroups v2 `cpu.weight` per QEMU process. | **`os-infrastructure`** is the Type I hypervisor that hosts the virtual machines running Totebox Archives and orchestration gateways. It manages a **per-node resource pool**: memory via `virtio_balloon` (inflation reclaims guest RAM into the node pool; deflation returns it) and CPU via cgroups v2 `cpu.weight` per QEMU process. |
| The pool is bounded to the physical node. Cross-node workload placement is the Totebox Orchestration layer's responsibility; once a VM is placed on a node, the hypervisor manages its local resource allocation. | The pool is bounded to the physical node. Cross-node workload placement is the Totebox Orchestration layer's responsibility; once a VM is placed on a node, the hypervisor manages its local resource allocation. |
| See: [[ppn-hypervisor-resource-pool]] | See: [[ppn-hypervisor-resource-pool]] |
| The planned distributed extension of this layer is intended to allow VMs to borrow compute from other physical nodes over the WireGuard mesh — using `virtio-mem` hot-plug memory blocks coordinated by a distributed capability ledger in `moonshot-protocol`. Cross-node memory lending, the automated balloon controller, and a cross-node VM scheduler are planned milestones; only the per-node pool is implemented today. | The planned distributed extension of this layer is intended to allow VMs to borrow compute from other physical nodes over the WireGuard mesh — using `virtio-mem` hot-plug memory blocks coordinated by a distributed capability ledger in `moonshot-protocol`. Cross-node memory lending, the automated balloon controller, and a cross-node VM scheduler are planned milestones; only the per-node pool is implemented today. |
| See also: [[ppn-distributed-vm-fabric]] | See also: [[ppn-distributed-vm-fabric]] |
| ### Totebox Orchestration layer | ### Totebox Orchestration layer |
| The Totebox Orchestration layer is the data plane. It runs inside the VMs managed by the hypervisor and is entirely separate from the PPN. | The Totebox Orchestration layer is the data plane. It runs inside the VMs managed by the hypervisor and is entirely separate from the PPN. |
| **Totebox Archives** (`cluster-totebox-*`) are sovereign data vaults — immutable WORM ledgers packaged as freely transferable bootable disk images. Each archive holds an Ed25519 keypair registered in `pairings.yaml`. It exposes data only via signed capability objects delivered over the PointSav Protocol (PSP). | **Totebox Archives** (`cluster-totebox-*`) are sovereign data vaults — immutable WORM ledgers packaged as freely transferable bootable disk images. Each archive holds an Ed25519 keypair registered in `pairings.yaml`. It exposes data only via signed capability objects delivered over the PointSav Protocol (PSP). |
| **`os-console`** is the keyboard-native operator terminal. It connects to one archive at a time (or many via `os-orchestration`) and is the free tier. | **`os-console`** is the keyboard-native operator terminal. It connects to one archive at a time (or many via `os-orchestration`) and is the free tier. |
| **`os-orchestration`** is a stateless multi-archive aggregator. It fans PSP queries across many archives simultaneously, returns only result rows (never raw records), and holds no keys of its own. It is the paid tier: multi-archive aggregation is the commercial boundary. | **`os-orchestration`** is a stateless multi-archive aggregator. It fans PSP queries across many archives simultaneously, returns only result rows (never raw records), and holds no keys of its own. It is the paid tier: multi-archive aggregation is the commercial boundary. |
| See: [[totebox-archive]], [[os-orchestration]] | See: [[totebox-archive]], [[os-orchestration]] |
| ## Three key properties | ## Three key properties |
| ### Isolation invariant | ### Isolation invariant |
| The hypervisor has zero read capability over VM-internal state. It knows a VM is consuming N pages of RAM and Y percent of vCPU time. It does not know whether the VM is running `os-totebox`, `os-orchestration`, or anything else. The Totebox Archive inside the VM knows nothing about balloon inflation, cgroup weights, or which physical node it is on. | The hypervisor has zero read capability over VM-internal state. It knows a VM is consuming N pages of RAM and Y percent of vCPU time. It does not know whether the VM is running `os-totebox`, `os-orchestration`, or anything else. The Totebox Archive inside the VM knows nothing about balloon inflation, cgroup weights, or which physical node it is on. |
| This means a compromise of the routing layer — the PPN — yields no access to archive contents. The two planes are structurally blind to each other. | This means a compromise of the routing layer — the PPN — yields no access to archive contents. The two planes are structurally blind to each other. |
| ### Freely transferable archives | ### Freely transferable archives |
| Because the hypervisor manages only VM lifecycle and resource allocation — not the data inside VMs — a Totebox Archive can be stopped, the disk image copied to any other PPN node, and restarted there without any change to its data or its identity. The destination node's hypervisor pool absorbs the workload. The archive's history, keys, and state are unchanged. | Because the hypervisor manages only VM lifecycle and resource allocation — not the data inside VMs — a Totebox Archive can be stopped, the disk image copied to any other PPN node, and restarted there without any change to its data or its identity. The destination node's hypervisor pool absorbs the workload. The archive's history, keys, and state are unchanged. |
| The disk image is the archive. The resource pool is node infrastructure. Moving the image moves the archive. | The disk image is the archive. The resource pool is node infrastructure. Moving the image moves the archive. |
| ### Zero crypto authority at the network plane | ### Zero crypto authority at the network plane |
| `os-network-admin` and the PPN mesh carry no cryptographic authority over archive data. Routing a node onto the mesh does not grant any data access. Removing a node from the mesh does not revoke any data access. Data access is governed entirely by `pairings.yaml` and the MBA keypair system — a separate plane with no connection to the PPN. | `os-network-admin` and the PPN mesh carry no cryptographic authority over archive data. Routing a node onto the mesh does not grant any data access. Removing a node from the mesh does not revoke any data access. Data access is governed entirely by `pairings.yaml` and the MBA keypair system — a separate plane with no connection to the PPN. |
| This separation is intentional: the network control plane and the data access plane are designed so that a failure or compromise of one does not cascade to the other. | This separation is intentional: the network control plane and the data access plane are designed so that a failure or compromise of one does not cascade to the other. |
| ## What PPN is not | ## What PPN is not |
| - **Not a data access layer.** PPN manages physical nodes. Archive data access goes through `os-console` or `os-orchestration` via MBA + PSP — not through WireGuard. | - **Not a data access layer.** PPN manages physical nodes. Archive data access goes through `os-console` or `os-orchestration` via MBA + PSP — not through WireGuard. |
| - **Not a compute scheduler.** `os-network-admin` does not schedule workloads across nodes. Cross-node placement is `gateway-orchestration-command-1`'s job (Totebox Orchestration layer). The hypervisor manages the local resource pool after placement. | - **Not a compute scheduler.** `os-network-admin` does not schedule workloads across nodes. Cross-node placement is `gateway-orchestration-command-1`'s job (Totebox Orchestration layer). The hypervisor manages the local resource pool after placement. |
| - **Not an identity authority.** The PPN mesh knows which physical nodes are enrolled. It does not know which operators are authorised to read which archives. That is `pairings.yaml`. | - **Not an identity authority.** The PPN mesh knows which physical nodes are enrolled. It does not know which operators are authorised to read which archives. That is `pairings.yaml`. |
| ## See also | ## See also |
| - [[sovereign-mesh]] — WireGuard overlay, 16-byte binary command protocol, hub-spoke topology | - [[sovereign-mesh]] — WireGuard overlay, 16-byte binary command protocol, hub-spoke topology |
| - [[genesis-protocol]] — autonomous first-boot bootstrap sequence, deferred fleet assembly | - [[genesis-protocol]] — autonomous first-boot bootstrap sequence, deferred fleet assembly |
| - [[ppn-command-protocol]] — the 16-byte binary wire format broadcast over UDP port 8090 | - [[ppn-command-protocol]] — the 16-byte binary wire format broadcast over UDP port 8090 |
| - [[service-pointsav-link]] — hot-pluggable adapter connecting os-* nodes to the fleet | - [[service-pointsav-link]] — hot-pluggable adapter connecting os-* nodes to the fleet |
| - [[os-network-admin]] — Foundation OS layer, zero crypto authority, node-join ceremony | - [[os-network-admin]] — Foundation OS layer, zero crypto authority, node-join ceremony |
| - [[ppn-hypervisor-resource-pool]] — per-node virtio_balloon + vCPU scheduling | - [[ppn-hypervisor-resource-pool]] — per-node virtio_balloon + vCPU scheduling |
| - [[totebox-archive]] — sovereign WORM data vault, freely transferable disk image | - [[totebox-archive]] — sovereign WORM data vault, freely transferable disk image |
| - [[os-orchestration]] — stateless PSP aggregator, multi-archive queries, paid tier | - [[os-orchestration]] — stateless PSP aggregator, multi-archive queries, paid tier |
| - [[ppn-distributed-vm-fabric]] — planned cross-node VM fabric: virtio-mem lending, distributed capability ledger, sovereign attestation | - [[ppn-distributed-vm-fabric]] — planned cross-node VM fabric: virtio-mem lending, distributed capability ledger, sovereign attestation |
| - [[pointsav-private-network|PointSav Private Network]] — infrastructure overview and WireGuard mesh provisioning context | - [[pointsav-private-network|PointSav Private Network]] — infrastructure overview and WireGuard mesh provisioning context |
| - [[enroll-ppn-node]] — step-by-step guide: register a compute node with the fleet controller and verify the first heartbeat | - [[enroll-ppn-node]] — step-by-step guide: register a compute node with the fleet controller and verify the first heartbeat |
| - [[add-a-fleet-node]] — step-by-step guide: enroll a second node into a running fleet without interrupting existing operations | - [[add-a-fleet-node]] — step-by-step guide: enroll a second node into a running fleet without interrupting existing operations |