Diff: systems/os-mediakit
From 17e01f7 to 17e01f7
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "OS Mediakit" | title: "OS Mediakit" |
| slug: os-mediakit | slug: os-mediakit |
| category: systems | category: systems |
| last_edited: 2026-05-29 | last_edited: 2026-05-29 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| status: stable | status: stable |
| bcsc_class: no-disclosure-implication | bcsc_class: no-disclosure-implication |
| --- | --- |
| **os-mediakit** is the guest operating system image for the `vm-mediakit` VM tier in | **os-mediakit** is the guest operating system image for the `vm-mediakit` VM tier in |
| the PointSav Private Network hypervisor layer. It isolates the MediaKit service surface | the PointSav Private Network hypervisor layer. It isolates the MediaKit service surface |
| — knowledge wikis, marketing sites, proofreader, and BIM orchestration — from the source | — knowledge wikis, marketing sites, proofreader, and BIM orchestration — from the source |
| vault and orchestration tiers. | vault and orchestration tiers. |
| --- | --- |
| ## Stack position | ## Stack position |
| The four-layer Totebox stack places os-mediakit in the **Hypervisor layer**: | The four-layer Totebox stack places os-mediakit in the **Hypervisor layer**: |
| ``` | ``` |
| Operator | Operator |
| ↓ | ↓ |
| PPN (WireGuard mesh, os-network-admin control plane) | PPN (WireGuard mesh, os-network-admin control plane) |
| ↓ | ↓ |
| Hypervisor layer ←— os-mediakit guest OS runs here | Hypervisor layer ←— os-mediakit guest OS runs here |
| ↓ | ↓ |
| Totebox Orchestration (app-mediakit-*, service-fs, system-core) | Totebox Orchestration (app-mediakit-*, service-fs, system-core) |
| ``` | ``` |
| os-mediakit is one guest among three in the three-VM layout: | os-mediakit is one guest among three in the three-VM layout: |
| | VM | Guest OS | Tier | | | VM | Guest OS | Tier | |
| |---|---|---| | |---|---|---| |
| | vm-workspace | host OS (Linux) | os-privategit (permanent host) | | | vm-workspace | host OS (Linux) | os-privategit (permanent host) | |
| | vm-intelligence | os-intelligence (planned) | os-totebox + inference | | | vm-intelligence | os-intelligence (planned) | os-totebox + inference | |
| | vm-mediakit | **os-mediakit** | os-mediakit | | | vm-mediakit | **os-mediakit** | os-mediakit | |
| The host — foundry-workspace GCP VM — runs QEMU to manage all guests. The hypervisor | The host — foundry-workspace GCP VM — runs QEMU to manage all guests. The hypervisor |
| itself is `os-infrastructure` (the Genesis Protocol boot layer). | itself is `os-infrastructure` (the Genesis Protocol boot layer). |
| --- | --- |
| ## Phase 1: Ubuntu 24.04 interim (present) | ## Phase 1: Ubuntu 24.04 interim (present) |
| The first deployment of vm-mediakit uses an **Ubuntu 24.04 server cloud x86_64 QCOW2** as | The first deployment of vm-mediakit uses an **Ubuntu 24.04 server cloud x86_64 QCOW2** as |
| the guest OS. This is the production interim while the seL4 Microkit image is developed. | the guest OS. This is the production interim while the seL4 Microkit image is developed. |
| Ubuntu 24.04 is required — not Debian 12 — because all service binaries compiled on the | Ubuntu 24.04 is required — not Debian 12 — because all service binaries compiled on the |
| GCP host (Ubuntu 24.04, glibc 2.39) link against `GLIBC_2.39` symbols. Debian 12 provides | GCP host (Ubuntu 24.04, glibc 2.39) link against `GLIBC_2.39` symbols. Debian 12 provides |
| only glibc 2.36 and would fail to execute the binaries at load time. | only glibc 2.36 and would fail to execute the binaries at load time. |
| What is running today: | What is running today: |
| - Ubuntu 24.04 booted via `provision-vm-mediakit.sh` under QEMU/TCG (GCP workspace has no | - Ubuntu 24.04 booted via `provision-vm-mediakit.sh` under QEMU/TCG (GCP workspace has no |
| hardware KVM; TCG is adequate for Phase 1 testing) | hardware KVM; TCG is adequate for Phase 1 testing) |
| - 6 GiB RAM (`-m 6144`), 20 GB QCOW2 disk | - 6 GiB RAM (`-m 6144`), 20 GB QCOW2 disk |
| - User-mode NAT networking: host port-forwards `1xxxx → :xxxx` for each service | - User-mode NAT networking: host port-forwards `1xxxx → :xxxx` for each service |
| - `virtio-balloon` device: dynamic RAM adjustment without guest reboot | - `virtio-balloon` device: dynamic RAM adjustment without guest reboot |
| - cloud-init first boot: hostname `vm-mediakit`, user `foundry`, systemd-native | - cloud-init first boot: hostname `vm-mediakit`, user `foundry`, systemd-native |
| - nginx/1.24.0 and build-essential installed post-boot | - nginx/1.24.0 and build-essential installed post-boot |
| Services running inside the Ubuntu 24.04 guest (Phase 1 state, 2026-05-29): | Services running inside the Ubuntu 24.04 guest (Phase 1 state, 2026-05-29): |
| | Service | Port | Purpose | Phase 1 status | | | Service | Port | Purpose | Phase 1 status | |
| |---|---|---|---| | |---|---|---|---| |
| | local-proofreader | 9092 | Proofreader service | ✓ active | | | local-proofreader | 9092 | Proofreader service | ✓ active | |
| | local-knowledge-documentation | 9090 | Documentation wiki | ✓ active | | | local-knowledge-documentation | 9090 | Documentation wiki | ✓ active | |
| | local-knowledge-corporate | 9095 | Corporate wiki | ✓ active | | | local-knowledge-corporate | 9095 | Corporate wiki | ✓ active | |
| | local-knowledge-projects | 9093 | Projects wiki | ✓ active | | | local-knowledge-projects | 9093 | Projects wiki | ✓ active | |
| | local-marketing-pointsav | 9101 | PointSav marketing site | ✓ active | | | local-marketing-pointsav | 9101 | PointSav marketing site | ✓ active | |
| | local-marketing | 9102 | Woodfine marketing site | ✓ active | | | local-marketing | 9102 | Woodfine marketing site | ✓ active | |
| | service-fs | 9100 | WORM ledger — data ingest backbone | pending (project-data build) | | | service-fs | 9100 | WORM ledger — data ingest backbone | pending (project-data build) | |
| | local-bim-orchestration | 9096 | BIM gateway | pending (depends on service-fs) | | | local-bim-orchestration | 9096 | BIM gateway | pending (depends on service-fs) | |
| | system-core | — | Capability Ledger substrate | pending (project-system install) | | | system-core | — | Capability Ledger substrate | pending (project-system install) | |
| | system-ledger | — | Ledger state-machine | pending (project-system install) | | | system-ledger | — | Ledger state-machine | pending (project-system install) | |
| The systemd host unit `infrastructure/local-vm-mediakit/vm-mediakit.service` manages the | The systemd host unit `infrastructure/local-vm-mediakit/vm-mediakit.service` manages the |
| QEMU process and handles graceful shutdown via the QEMU monitor socket. | QEMU process and handles graceful shutdown via the QEMU monitor socket. |
| --- | --- |
| ## Phase 3: seL4 Microkit image (planned) | ## Phase 3: seL4 Microkit image (planned) |
| The intended long-term form of os-mediakit is a **seL4 Microkit 2.2 AArch64 image** | The intended long-term form of os-mediakit is a **seL4 Microkit 2.2 AArch64 image** |
| assembled by `moonshot-toolkit`. Each service runs as an isolated seL4 Protection Domain | assembled by `moonshot-toolkit`. Each service runs as an isolated seL4 Protection Domain |
| (PD) within the formally-verified microkernel. | (PD) within the formally-verified microkernel. |
| This is a planned milestone. The seL4 path requires an AArch64 host (Microkit 2.2.0 | This is a planned milestone. The seL4 path requires an AArch64 host (Microkit 2.2.0 |
| supports AArch64 and RISC-V 64; there is no x86_64 Microkit target). | supports AArch64 and RISC-V 64; there is no x86_64 Microkit target). |
| ### Planned component layout | ### Planned component layout |
| Each major service becomes a seL4 PD with minimal capability set: | Each major service becomes a seL4 PD with minimal capability set: |
| | PD | Binary | seL4 capability | | | PD | Binary | seL4 capability | |
| |---|---|---| | |---|---|---| |
| | `mediakit-root` | os-mediakit rootserver | Bootstrap, capability distribution | | | `mediakit-root` | os-mediakit rootserver | Bootstrap, capability distribution | |
| | `service-fs-pd` | service-fs Envelope B | IPC to ledger-pd; file-system endpoint only | | | `service-fs-pd` | service-fs Envelope B | IPC to ledger-pd; file-system endpoint only | |
| | `system-ledger-pd` | system-ledger (native feature) | seL4_Call to capability oracle | | | `system-ledger-pd` | system-ledger (native feature) | seL4_Call to capability oracle | |
| | `proofreader-pd` | service-proofreader | HTTP endpoint; no FS capability | | | `proofreader-pd` | service-proofreader | HTTP endpoint; no FS capability | |
| | `knowledge-pd` | app-mediakit-knowledge | HTTP endpoint; read-only FS cap | | | `knowledge-pd` | app-mediakit-knowledge | HTTP endpoint; read-only FS cap | |
| | `marketing-pd` | app-mediakit-marketing | HTTP endpoint; no FS capability | | | `marketing-pd` | app-mediakit-marketing | HTTP endpoint; no FS capability | |
| The isolation invariant: no PD has read capability over another PD's memory. Enforced by | The isolation invariant: no PD has read capability over another PD's memory. Enforced by |
| the seL4 capability model — not by OS-level permissions. | the seL4 capability model — not by OS-level permissions. |
| ### The `system-substrate-sel4` shim | ### The `system-substrate-sel4` shim |
| `system-core` and `system-ledger` are written for `std` environments (Linux daemon form). | `system-core` and `system-ledger` are written for `std` environments (Linux daemon form). |
| Running them as seL4 PDs requires `system-substrate-sel4` — a shim crate with feature flags | Running them as seL4 PDs requires `system-substrate-sel4` — a shim crate with feature flags |
| `["native"]` (seL4_Call/seL4_Send via rust-sel4) and `["compat"]` (std wrapper for Linux). | `["native"]` (seL4_Call/seL4_Send via rust-sel4) and `["compat"]` (std wrapper for Linux). |
| The shim is a planned crate. The same pattern applies to service-fs specifically (Envelope B). | The shim is a planned crate. The same pattern applies to service-fs specifically (Envelope B). |
| ### Assembly | ### Assembly |
| `moonshot-toolkit build os-mediakit/system-spec.toml` is the intended build command. | `moonshot-toolkit build os-mediakit/system-spec.toml` is the intended build command. |
| `system-spec.toml` declares the PDs, memory regions, and channels in a Microkit-shaped | `system-spec.toml` declares the PDs, memory regions, and channels in a Microkit-shaped |
| TOML format. The output `build/system-image.bin` is bootable on any seL4-supported | TOML format. The output `build/system-image.bin` is bootable on any seL4-supported |
| AArch64 platform (qemu-arm-virt, Raspberry Pi 4, AWS Graviton). | AArch64 platform (qemu-arm-virt, Raspberry Pi 4, AWS Graviton). |
| --- | --- |
| ## What changes vs Phase 1, what stays the same | ## What changes vs Phase 1, what stays the same |
| | Property | Ubuntu 24.04 (Phase 1) | seL4 Microkit (Phase 3, planned) | | | Property | Ubuntu 24.04 (Phase 1) | seL4 Microkit (Phase 3, planned) | |
| |---|---|---| | |---|---|---| |
| | Guest OS | Ubuntu 24.04 Linux 6.x (glibc 2.39) | seL4 microkernel + Microkit PDs | | | Guest OS | Ubuntu 24.04 Linux 6.x (glibc 2.39) | seL4 microkernel + Microkit PDs | |
| | Host | QEMU/TCG (x86_64) | QEMU/KVM or bare metal AArch64 | | | Host | QEMU/TCG (x86_64) | QEMU/KVM or bare metal AArch64 | |
| | Service binaries | Same (cross-compiled) | Same (recompiled for AArch64 no_std) | | | Service binaries | Same (cross-compiled) | Same (recompiled for AArch64 no_std) | |
| | Wire protocols | CBOR-over-HTTP | CBOR-over-QUIC (same data schema) | | | Wire protocols | CBOR-over-HTTP | CBOR-over-QUIC (same data schema) | |
| | Port numbers | Same (9090, 9092, ...) | Same (WireGuard overlay) | | | Port numbers | Same (9090, 9092, ...) | Same (WireGuard overlay) | |
| | virtio-balloon | Present | Present (hypervisor layer unchanged) | | | virtio-balloon | Present | Present (hypervisor layer unchanged) | |
| | Formal isolation | Linux kernel security model | seL4 intransitive non-interference proof | | | Formal isolation | Linux kernel security model | seL4 intransitive non-interference proof | |
| | Key custody | OS file permissions | seL4 capability object — no OS | | | Key custody | OS file permissions | seL4 capability object — no OS | |
| --- | --- |
| ## Relationship to os-infrastructure and Genesis Protocol | ## Relationship to os-infrastructure and Genesis Protocol |
| `os-infrastructure` is the hypervisor boot layer — it runs Genesis Protocol on the physical | `os-infrastructure` is the hypervisor boot layer — it runs Genesis Protocol on the physical |
| host to establish the PPN node's WireGuard identity and claim ceremony. os-mediakit is a | host to establish the PPN node's WireGuard identity and claim ceremony. os-mediakit is a |
| *guest* that runs above os-infrastructure. They are different layers and different binaries. | *guest* that runs above os-infrastructure. They are different layers and different binaries. |
| The Genesis Protocol first-boot sequence applies to the **host node** | The Genesis Protocol first-boot sequence applies to the **host node** |
| (os-infrastructure), not to the guest (os-mediakit). A new vm-mediakit guest joins the mesh | (os-infrastructure), not to the guest (os-mediakit). A new vm-mediakit guest joins the mesh |
| via the MBA pairing ceremony after the host node is already a PPN member. | via the MBA pairing ceremony after the host node is already a PPN member. |
| --- | --- |
| ## See also | ## See also |
| - [[ppn-hypervisor-resource-pool]] — how virtio-balloon manages RAM for vm-mediakit | - [[ppn-hypervisor-resource-pool]] — how virtio-balloon manages RAM for vm-mediakit |
| - [[totebox-archive]] — what the Totebox Archive tier does above the guest OS | - [[totebox-archive]] — what the Totebox Archive tier does above the guest OS |
| - [[os-network-admin]] — the PPN control plane; vm-mediakit joins the mesh through it | - [[os-network-admin]] — the PPN control plane; vm-mediakit joins the mesh through it |