Campus architecture

Campus separates global product decisions, node-local execution, and application traffic. Campus Mux is a control-plane communication bridge only. A Campus Node composes Runtime + Gateway, with optional embedded Ingress. Gateway is the only component allowed to translate remote private or HTTP/WebSocket application traffic into an installation's private backend protocol. The sole implemented exception is Runtime-managed, declared-and-granted direct UDP for native protocols such as WireGuard.

Account MCP follows the same boundary: CampusOS constructs and authorizes the account-scoped tool catalog, then Gateway carries only the admitted fixed-path invocation and may request an interface-call wake. Runtime and Gateway do not evaluate owner, selected-user, Contacts, public, or app permission policy. See Campus account MCP for the component and sequence diagrams.

flowchart LR
  OS["CampusOS control plane"] -->|"local HTTP control"| Mux["Campus Mux"]
  OS -->|"authenticated topology snapshots"| Ingress["Campus Ingress"]
  Mux -->|"Iroh control"| Runtime["Campus Node Runtime"]
  Runtime -->|"local supervisor / UDS"| VM["Firecracker VM"]

  Private["Web or native frontend"] -->|"CampusSDK + Iroh"| Gateway["Per-installation Campus Gateway"]
  BrowserApp["Browser app SDK"] -->|"typed request only"| Shell["Trusted CampusOS shell"]
  Shell -->|"exact ticket + PRF-unlocked recipient over Iroh"| Gateway
  Public["Public client"] --> Ingress["Campus Ingress"]
  Ingress -->|"Iroh ingress"| Gateway
  NativeUDP["Native UDP client"] -->|"assigned direct UDP port"| Runtime
  Runtime -->|"declared container UDP port"| Backend
  Gateway <-->|"TAP / local socket"| Backend["App backend in VM"]
  Backend -->|"Campus services / sealed egress"| Gateway
  Gateway -->|"authorization metadata"| OS
  Gateway -->|"credential injection + request body"| Providers["Approved external providers"]
  FileCaller["Authorized browser or app backend"] -->|"signed direct blob transfer"| Blobs["Local blob store or Spaces"]
  OS -->|"logical metadata + transfer grants"| FileCaller
  MCPClient["Agent or MCP client"] -->|"account MCP HTTP"| OS
  OS -->|"admitted MCP ingress"| Gateway

Enforced boundaries

• CampusOS sends desired lifecycle commands to Runtime through Mux. Mux never carries frontend, public endpoint, MCP, or backend service traffic and owns no scheduling or placement policy.
• CampusOS owns user lifecycle settings, foreground and work leases, account cron bindings, and always-on reconciliation. Runtime owns the final machine state and accepts a Gateway wake only for a trigger present in the current instance spec. See Background execution.
• Runtime owns installation lifecycle and starts one gateway for each installation. It does not become an application reverse proxy.
• The web/native launch descriptor contains only the private Gateway EndpointId, endpoint ticket, scoped capability, and any authorized Runtime-published port descriptors. It never contains a backend address or HTTP public topology.
• The backend receives an installation-local Gateway credential and a gateway-local Campus API URL. It does not receive the Gateway's CampusOS credential, installation recipient private key, provider secret, or CampusOS session.
• Runtime creates that recipient key on the selected Node. CampusOS stores its public half and the hash of a separate Gateway broker bearer. The per-installation Gateway alone combines the host-held key with an authorized envelope, injects the credential, and forwards the original body. CampusOS sees policy/budget metadata, not provider payloads. See Installation-sealed secrets.
• Raw object storage uses the same provider-key boundary. The guest sees a local S3-compatible Gateway endpoint and installation-local placeholder credentials. Gateway confines requests to the CampusOS-derived bucket/prefix and signs the provider hop with the real host-held key.
• Interactive browser intelligence uses a separate account recipient. Its private scalar is inside a WebAuthn-PRF-encrypted user-secrets bundle, is unlocked only in trusted-shell memory, and is sent over Iroh to the exact installation Gateway. A frontend-only installation receives a Gateway-only Runtime target without a publisher workload or filesystem. CampusOS stores the public key and ciphertext but never receives the PRF result, private scalar, prompt, or provider response.
• CampusOS persists the hostname → Gateway EndpointId topology and pushes revisioned full snapshots over persistent authenticated WebSockets to Ingress. Gateway independently re-checks the attached hostname and granted method/path. User-supplied authorization, cookies, and forwarding markers are stripped.
• The gateway attaches the backend only over a node-local address. Runtime status exposes gateway ingress information to CampusOS, not that backend address.
• A schema-version-4 publicPorts declaration plus the exact fixed-port or UDP:autoendpoints.public.udp installation grant authorizes Runtime to publish only that UDP port. Runtime chooses the host port and reports the configured public host; the path bypasses Ingress/Gateway and therefore relies on the native protocol's authentication. A separate runtime.network-tunnel grant maps only to NET_ADMIN plus /dev/net/tun, never arbitrary capabilities or devices.
• For the all-in Campus active-hour product, Runtime reports authoritative instance state and enforces only a short account deadline. CampusOS derives binary account activity, the Campus Seller verifies an Ark/VAS payment proof, and only then renews that deadline. Mux remains policy-free, Wallet cannot self-credit, and BYOH specs do not request paid Campus authorization. See Campus active-hour billing.
• Campus-managed intelligence follows the same placement boundary for workload and browser recipients: it is authorized only for an installation placed in the campus-hosted pool. BYOH may use BYOK, sealed to a workload or browser recipient, but cannot consume Campus-managed provider credentials.
• The Campus Seller itself is a private, non-default application owned by the ordinary master account and placed on that account's own Node. CampusOS reaches it through its installation Gateway using authenticated control-plane ingress; it has no special Runtime path. See Platform master account.
• Logical storage stays outside the workload lifecycle. CampusOS authorizes logical ownership and ACLs and signs a short transfer grant; the authorized browser or backend moves immutable bytes directly to the blob provider. Blob storage never receives the CampusOS session or app service credential. See Campus Drive and logical storage.

Current local substitutions

The repository is a single-machine vertical slice, so two production components are represented by local adapters:

• Docker plus a no-masquerade bridge remains an explicit development fallback. On a Linux/KVM host, Firecracker specs run through matching-version jailer, per-installation chroots/UIDs/cgroups, and per-TAP policy; the fallback is used only when CampusOS explicitly allows it.
• The per-installation gateway is split across a host Iroh/ingress process and an app-service sidecar on Docker's networks. Both are the same Rust gateway implementation and use separate installation credentials. Firecracker replaces this packaging detail with one node-local gateway connected to the VM through TAP/local IPC.
• The Docker Gateway image is part of the Runtime binary contract. Before Runtime accepts control, it runs the image's hidden campus-gateway image-contract probe and compares the result with the contract compiled into Runtime. A missing or stale image fails Node startup with the exact rebuild command; it must never be allowed to degrade later into app warm/connect 500s or misleading app API 404s. The protected credential-file interface is credentials-file-v1.
• The standalone or embedded campus-ingress role is the only public HTTP/WebSocket application adapter. Its routing table is an in-memory copy of CampusOS topology, and it uses Iroh for the edge-to-node hop. Runtime-managed direct UDP is a distinct native-protocol adapter and is implemented by Docker publication and scoped Firecracker TAP DNAT/FORWARD rules.
• The filesystem-backed Rust campus-blob-store substitutes for Spaces. It implements only the Campus signed direct-transfer contract, so SDK and CampusOS behavior remain provider-independent.

Private browser/native SDK traffic already uses Iroh directly to the installation gateway. Backend Campus service traffic now goes through the same per-installation gateway. The former shared Node campus-service-gateway has been removed.

CampusOS topology reconciliation and passkey-mediated native private-endpoint delivery are control-plane concerns; neither changes the Runtime-to-VM or Gateway-to-backend boundaries above.