Proposal: Capability-Based Service Architecture

How capOS processes receive authority, compose into services, and expose layered capabilities — without a service manager daemon.

Problem

Traditional OSes grant processes ambient authority (file system, network, IPC namespaces) and then restrict it via sandboxing (seccomp, namespaces, AppArmor). Service managers like systemd handle dependencies, lifecycle, and resource limits through a central daemon with a massive configuration surface.

capOS inverts this: processes start with zero authority and receive only the capabilities they need. The capability graph implicitly encodes service dependencies, resource limits, and access control. No central daemon required.

Process Startup Model

A process receives its entire authority as a set of named capabilities at spawn time. There is no ambient authority to fall back on — if a capability wasn’t granted, the operation is impossible.

The child process sees its granted capabilities by name. It cannot discover or request capabilities it wasn’t given.

Capability Layering

Each process consumes lower-level capabilities and exports higher-level ones. Authority narrows at every layer:

Kernel
  │
  ├─ Nic cap (raw frame send/receive for one device)
  ├─ Timer cap (monotonic clock)
  ├─ DeviceMmio cap (one device's BAR regions)
  └─ Interrupt cap (one IRQ line)
       │
       v
NIC Driver Process
  │
  └─ Nic cap ──> Network Stack Process
                   │
                   ├─ TcpSocket cap (one connection)
                   ├─ UdpSocket cap (one socket)
                   └─ NetworkManager cap (create sockets)
                        │
                        v
                   HTTP Service Process
                     │
                     ├─ Fetch cap (any URL)
                     │    │
                     │    v
                     │  Trusted Process (holds Fetch, mints scoped caps)
                     │
                     └─ HttpEndpoint cap (one origin)
                          │
                          v
                     Application Process

The application at the bottom holds an HttpEndpoint cap scoped to a single origin. It cannot make raw TCP connections, send arbitrary packets, or touch any device. The capability is the security policy.

HTTP Capabilities

Two levels of HTTP capability: Fetch (general) and HttpEndpoint (scoped). HttpEndpoint is implemented by a process that holds a Fetch cap and restricts it.

Fetch

Unrestricted HTTP access — equivalent to the browser Fetch API. The holder can make requests to any URL. This is the base capability that HTTP service processes use internally.

interface Fetch {
    # General-purpose HTTP request to any URL.
    request @0 (url :Text, method :Text, headers :List(Header), body :Data)
        -> (status :UInt16, headers :List(Header), body :Data);
}

struct Header {
    name @0 :Text;
    value @1 :Text;
}

Fetch is powerful — granting it is roughly equivalent to granting arbitrary outbound network access. It should only be held by service processes that need to make requests on behalf of others, not by application code directly.

HttpEndpoint

A restricted view of Fetch, scoped to a single origin. The holder can only make requests within the bounds encoded in the capability.

interface HttpEndpoint {
    # Request scoped to this endpoint's origin.
    # Path is relative (e.g., "/v1/users").
    request @0 (method :Text, path :Text, headers :List(Header), body :Data)
        -> (status :UInt16, headers :List(Header), body :Data);
}

Note: same request() signature as Fetch, but path instead of url. The origin is implicit — bound into the capability at mint time.

Attenuation

A process holding Fetch mints HttpEndpoint caps by narrowing authority. The core restriction is always origin — Fetch can reach any URL, HttpEndpoint is locked to one host. Additional constraints (path prefixes, method restrictions, rate limits) are possible but are userspace policy details, not OS-level concerns.

This is the standard object-capability attenuation pattern: same interface, less authority. The application code is identical whether it holds a broad or narrow HttpEndpoint.

Boot and Initialization Sequence

The kernel doesn’t know about services. It boots, creates a handful of kernel-provided caps, and spawns exactly one process: init. Everything else is init’s responsibility.

Current State vs Target State

The implementation has crossed the single-init startup milestone and the 15.4 schema split. SystemManifest now carries schemaVersion, binaries, initConfig, and kernelParams. The Cap’n Proto schema no longer exposes ServiceEntry, ServiceCapSource, CapRef, exports, or restart policy as kernel-consumed fields. Those service-graph concepts remain as Rust parsing types inside capos-config because the focused init executor still interprets initConfig.services.

Each process now also carries an immutable session context produced at spawn time by kernel/src/session_context.rs; default inheritance comes from the parent’s session context, and a broker can select a child session through the AuthorityBroker/UserSession path. This invocation context is the basis for session-scoped audit attribution and identity-policy enforcement; see User Identity and Policy and make run-session-context for the one-session-per-process proof.

Current manifests put the first process description at initConfig.init. The default system.cue manifest now boots the separate init binary with BootPackage and ProcessSpawner; that init process reads initConfig.services and starts the shell, remote-session CapSet gateway, chat server, and resident demo services. Focused shell-led manifests such as system-smoke.cue and system-shell.cue still boot capos-shell as the lone init process for narrow login/shell proofs. Focused init-executor manifests such as system-spawn.cue, system-chat.cue, and system-adventure.cue boot the separate init binary with BootPackage and ProcessSpawner; that init process reads initConfig.services and resolves the remaining service graph through ProcessSpawner. Other focused single-service or harness manifests still boot a demo/service binary as the init process for narrow proofs. The kernel validates only the kernel-owned boot boundary: schema version, binaries, kernelParams, initConfig.init.binary, and kernel-sourced initConfig.init.caps.

Current Bootstrap Ownership Inventory

As of 2026-05-13, the repo is in the schema-split init-owned startup state:

• schema/capos.capnp defines SystemManifest as schemaVersion, binaries, initConfig, and kernelParams. Service graph fields are not Cap’n Proto schema fields.
• capos-config/src/manifest.rs still defines ServiceEntry, CapRef, CapSource::Kernel, CapSource::Service, and RestartPolicy as internal Rust types for parsing initConfig.services.
• tools/mkmanifest still embeds every declared binary into the manifest and validates the full init-owned graph before writing manifest.bin.
• capos-config/src/validation.rs separates kernel bootstrap validation from init graph validation. Kernel bootstrap validation covers binary names, initConfig.init.binary, init kernel cap sources, and kernelParams. Full graph validation covers initConfig.services for mkmanifest and init’s metadata-only ManifestBootstrapPlan path.
• kernel/src/main.rs::run_init reads the Limine manifest module, validates the kernel-owned bootstrap contract, configures serial policy from kernelParams, and loads only initConfig.init.binary.
• kernel/src/cap/mod.rs::create_boot_service_caps builds only initConfig.init.caps. Those caps are kernel-sourced by type, so the kernel has no CapSource::Service branch.
• The init cap bundle is currently described by initConfig.init.caps. In the default system.cue manifest this grants the separate init binary the bootstrap caps it needs to read BootPackage and spawn the service graph. In focused shell-led manifests such as system-smoke.cue, this still grants capos-shell terminal, credential, session, audit, and broker capabilities directly. In focused single-service or harness manifests, initConfig.init.caps grants only the capabilities the harness itself needs.
• BootPackage exposes the full serialized manifest bytes to init. That path is live for default and focused init-executor manifests. Focused shell-led manifests do not grant BootPackage to capos-shell.
• ProcessSpawner owns the embedded binary set. It receives the boot manifest bytes so delegated ProcessSpawner grants can preserve that same boot package context; child BootPackage caps are not minted from SpawnGrantSource::Kernel. ProcessSpawner.createPipe(bufferBytes) mints a bounded SPSC kernel Pipe capability used by the POSIX adapter Phase P1.3 recording-shim fork-for-exec path; see POSIX Adapter §Phase P1.3 and Userspace Binaries Part 4.
• ProcessSpawner.spawn resolves SpawnGrantSource::Kernel for the bounded manager-issued DDF authority surfaces (DeviceMmio, DMAPool, Interrupt, HardwareAuditLog) through the matching grant-source records in kernel/src/cap/devicemmio_grant_source.rs, kernel/src/cap/dmapool_grant_source.rs, and their interrupt/audit peers. Each grant attaches a fresh manager-owned record, validates owner/quiesce/ scrub state for DMA-side caps, and returns a child-local handle without sharing the parent’s owner object. See device-driver-foundation.md Task 5 for the bounded-authority scope and the focused make run-devicemmio-grant, make run-dmapool-grant, make run-interrupt-grant, and make run-hardware-audit smokes.
• init/src/main.rs is the focused BootPackage executor. When that binary is the init process, it reads the BootPackage manifest, builds a ManifestBootstrapPlan, validates it again, discovers its own kernel grants from initConfig.init.caps plus the CapSet, preflights the initConfig.services graph, resolves kernel and service cap sources, records exports, spawns children through ProcessSpawner, and waits on their ProcessHandles.
• system.cue, system-smoke.cue, system-spawn.cue, system-chat.cue, system-adventure.cue, and the other focused manifests now express their first-process bundle under initConfig.init and any child topology under initConfig.services.

The practical cleanup boundary is therefore not “move service startup to init”; that already happened. The current cleanup target is narrower: the kernel no longer understands the service graph as a bootstrap authority structure. The remaining future cleanup is to stop letting focused harnesses choose arbitrary init binaries and direct kernel cap bundles, then move to one fixed generic-init ABI.

Narrowed Transitional Contract

The current schema is schemaVersion, binaries, initConfig, and kernelParams. The narrowed kernel contract is:

• The kernel validates schemaVersion, parses kernelParams for kernel-consumed boot policy, and configures serial policy.
• The kernel resolves only initConfig.init.binary against binaries and loads only that ELF.
• The kernel may interpret initConfig.init.caps only as the bootstrap cap bundle for the single first process. Those caps must be kernel-sourced; a service-sourced cap in initConfig.init.caps is invalid because no non-init service exists at kernel handoff time.
• initConfig.services[*], their caps, exports, restart, and any CapSource::Service references are init-owned configuration while the transitional Rust parser exists. mkmanifest and init continue validating them for smoke coverage, but kernel bootstrap does not run the multi-service graph validator or a service export resolver.
• Focused harness manifests that intentionally boot a demo/service binary as init stay valid during this slice. Their harness-specific caps are still described by initConfig.init.caps until those smokes are migrated behind a generic init-owned executor config.

Kernel bootstrap implements this contract with a first-service cap-table builder. That builder covers only implemented kernel sources used by current initConfig.init.caps lists. That current first-service surface is wider than the eventual generic-init minimum: the default init-owned path needs Console, TerminalSession, CredentialStore, SessionManager, AuditLog, AuthorityBroker, BootPackage, ProcessSpawner, listener, launcher, and chat endpoint authority so it can launch the current service graph; focused shell-led paths still need TerminalSession, CredentialStore, SessionManager, AuditLog, and AuthorityBroker directly; focused harnesses need their own direct kernel caps. Cross-service export lookup, service-source attenuation, and non-init cap-resolution policy stay in init/src/main.rs for the focused BootPackage-executor manifests.

Target Boot Package Contract

After the harness migration, SystemManifest should keep the same outer shape but initConfig.init should stop being a per-manifest kernel bootstrap bundle. At that point:

• ServiceEntry, CapRef, CapSource::Service, service exports, and restart policy remain ordinary data inside initConfig, interpreted and validated by init or a supervisor service.
• Kernel validation is limited to the schema version, kernel parameters, boot-package integrity/measurement policy, and enough binary metadata to load the one init image.
• The first process is the generic init/supervisor, not a demo harness or shell. Shell-led and focused single-service proofs should become init-owned configurations rather than alternate kernel bootstrap contracts.
• The fixed direct kernel bundle for that generic init starts with Console, BootPackage, and ProcessSpawner in the currently implemented system. This is the target generic-init minimum, not the full transitional initConfig.init.caps surface. The architecture-level target also includes Timer, DeviceManager, FrameAllocator, and per-process VirtualMemory once those authorities are ready to be part of init’s stable bootstrap ABI. Until then, FrameAllocator, VirtualMemory, and Endpoint grants for child processes remain minted through ProcessSpawner spawn grants.

The target model removes the kernel-side service graph entirely. The manifest stops being a kernel authority graph and becomes a boot package delivered to init:

• List of embedded binaries (init needs them before any storage service exists; they can’t be fetched from a filesystem that hasn’t started).
• Init’s config blob (CUE-encoded tree; what to spawn, with what attenuations, with what restart policy).
• Kernel boot parameters (memory limits, feature flags) consumed by the kernel itself, not forwarded to init.

The kernel spawns exactly one userspace process (init) with a fixed cap bundle:

• Console — kernel serial wrapper (may be replaced later by a userspace log service, with init retaining a direct console cap for emergency use).
• ProcessSpawner — only init and its delegated supervisors hold this.
• FrameAllocator — physical frame authority for init’s own allocations.
• VirtualMemory — per-process address-space authority for init.
• DeviceManager — enumerate/claim devices; init delegates device-specific slices to drivers.
• Timer — monotonic clock.
• BootPackage — read-only cap exposing the embedded binaries and the config blob.

Everything else — drivers, net-stack, filesystems, supervisors, apps — init spawns at runtime via ProcessSpawner with appropriate attenuation. No manifest ServiceEntry, no cross-service CapRef, no manifest exports.

Pre-Init Boundary After Stage 6

Rule of thumb: no userspace service runs before init. The kernel’s job is primitive cap synthesis and a single-process handoff; init’s job is the whole service graph. Concretely, after Stage 6:

• Stays in kernel pre-init: memory map ingest, frame allocator, heap, paging, GDT/IDT/TSS, serial for kernel diagnostics, scheduler, ring dispatch, kernel-cap CapObject impls, ELF loading for init, boot package measurement (if attested boot is added).
• Stays in manifest: binaries list + init config blob + kernel boot params. Schema-wise, ServiceEntry and CapSource::Service disappear; SystemManifest shrinks to binaries + initConfig + kernelParams.
• Moves to init: service topology, cross-service cap wiring, attenuation, restart policies, dynamic spawn, cap export/import, supervision trees. Anything a service manager would do.
• Moves to init or later services: logging policy, config store, secrets, filesystem mounts, network configuration, device binding.

Edge cases that might look like they want a pre-init service but don’t:

• Early crash / panic handling. Kernel-side panic handler, no service needed.
• Recovery shell. Kernel fallback: if init fails to reach a healthy state within a timeout (e.g. exits immediately, or never issues a liveness SQE), kernel optionally spawns a “recovery” binary from the boot package with the same cap bundle. Still just one userspace process at a time pre-supervisor-loop.
• Attested/measured boot. Kernel hashes binaries in the boot package before handing BootPackage to init. The measurement agent, if any, runs as a normal service spawned by init with a cap to the sealed measurements.
• Early-boot console. Kernel owns serial and exposes Console to init. A userspace log service can layer on top later; it is not pre-init.

Legacy Manifest Fields After Stage 6

ServiceEntry.caps, CapSource::Service, and ServiceEntry.exports are transitional init configuration, not kernel schema. The 15.4 schema split deleted them from schema/capos.capnp, collapsed the service graph into initConfig: CueValue, and kept kernel bootstrap on the first-service cap-table builder. The remaining cleanup is to make that first-service bundle fixed rather than manifest-selected:

1. Move shell-led and focused harness proofs behind an init-owned executor config instead of booting their binaries directly as init.
2. Embed or otherwise pin the generic init image as the only kernel-loaded userspace image. Partially landed (2026-05-25 23:26 UTC): the init image is embedded and loaded from kernel::boot::INIT_ELF whenever init.binary == "init" (see “Init Binary Embedding”). It is not yet the only kernel-loaded image — until step 1 moves the focused/shell proofs behind an init-owned executor, non-"init" PID-1 selectors are still kernel-loaded from binaries.
3. Replace per-manifest initConfig.init.caps with the fixed bootstrap cap bundle described above plus BootPackage.
4. Keep initConfig.services as ordinary init/supervisor configuration until a later libcapos or supervisor API gives it a more concrete format.

The re-export restriction added in capos-config::validate_manifest_graph (service A exports cap sourced from B.ep) becomes moot at that point because there are no kernel-owned manifest exports at all. It stays as defensive validation for initConfig.services while the transitional init-owned executor exists.

Init Binary Embedding

Status: landed 2026-05-25 23:26 UTC as a hybrid keyed on the reserved init selector (see below). Init is part of the kernel’s bootstrap contract, not a configuration choice: the cap bundle handed to init is a kernel ABI, the _start(ring, pid, …) entry shape is a kernel ABI, and a version-mismatched init is a footgun with no payoff in a single-init research OS. So the init ELF ships inside the kernel binary via include_bytes!, not as a separate manifest entry or Limine module.

Shape (as landed):

• init/ stays a standalone crate with its own linker script and code model (user-space base 0x200000, static relocation model, 4 KiB alignment). Not a workspace member; different build flags than the kernel.
• kernel/build.rs reads the prebuilt init/ artifact (the Makefile passes CAPOS_INIT_ELF and orders init before the kernel; a conventional-path fallback covers a bare cargo build after init is built) and emits an include_bytes!("…") into a kernel::boot::INIT_ELF: &[u8] static. Driving init’s build from build.rs was rejected to avoid duplicating its custom target/code-model flags; failing closed on a missing artifact is the chosen behavior.
• initConfig.init.binary is a generic “which binary is PID 1” selector, so embedding is keyed on the reserved name capos_config::RESERVED_INIT_BINARY_NAME ("init"). When init.binary == "init", kernel bootstrap parses INIT_ELF through the same capos_lib::elf path used for service binaries, creates the init address space via AddressSpace::new_user(), loads segments, populates the cap bundle (including BootPackage), and jumps — no Limine module lookup and no binaries resolution for that identity. When init.binary names any other binary (the shell on run-smoke, the ~70 focused test-as-PID-1 manifests), PID 1 still resolves from SystemManifest.binaries exactly as before.
• The reserved name "init" must not appear in SystemManifest.binaries: manifest validation (capos-config and mkmanifest) rejects it, since the kernel owns the init image. Real-init manifests drop their init entry; their binaries list is services-only.
• The embedded image is the canonical init binary, so init’s own child spawns that reference init by name (e.g. system-spawn.cue’s spawn-hardening fixtures) still resolve: when init is embedded, run_init injects the embedded bytes into the ProcessSpawner binary set under the reserved name (the BootPackage cap serves only the serialized manifest bytes, which never carry the reserved entry). This keeps the spawnable set identical to the pre-embedding state without init re-entering the serialized manifest. Service binaries remain distinct BootPackage blobs.
• Measured-boot attestation (if added) covers the kernel ELF, which transitively covers init’s bytes. Service binaries are hashed separately by the kernel before handing BootPackage to init.

What this does not change:

• Init still runs in Ring 3 with its own page tables; embedding is byte packaging, not privilege merging.
• Init is still ELF-parsed at boot — the same loader and W^X enforcement apply. The only thing different is where the bytes came from.
• Service binaries (everything spawned after init) stay in the boot package as distinct blobs, exposed to init via BootPackage. They are not linked into the kernel; their lifecycle is independent of the kernel’s.

What option was rejected: fully linking init into the kernel crate (shared compilation unit, shared text). That collapses the kernel/user build boundary, couples linker scripts and code models, and puts init’s panics/UB inside the kernel’s compilation context. The process-isolation boundary survives that arrangement — but the build-time separation that makes the boundary trustworthy does not. include_bytes! preserves the separation; static linking destroys it.

Kernel boot
  │
  ├─ Create kernel caps: Console, Timer, DeviceManager, ProcessSpawner
  │
  └─ Spawn init with all kernel caps
       │
       init process (PID 1)
         │
         ├─ Phase 1: Core services (sequential — each depends on previous)
         │    ├─ DeviceManager.enumerate() → list of devices
         │    ├─ Spawn NIC driver with device-specific caps
         │    ├─ Wait for NIC driver to export Nic cap
         │    ├─ Spawn net-stack with Nic + Timer caps
         │    └─ Wait for net-stack to export NetworkManager cap
         │
         ├─ Phase 2: Higher-level services (can be parallel)
         │    ├─ Spawn http-service with TcpSocket cap from net-stack
         │    ├─ Spawn dns-resolver with UdpSocket cap
         │    └─ ...
         │
         └─ Phase 3: Applications
              ├─ Spawn app-a with HttpEndpoint("api.example.com")
              ├─ Spawn app-b with Fetch cap (trusted)
              └─ ...

The Init Process in Detail

Init is a regular userspace process with privileged caps. It is the only process that holds ProcessSpawner (the right to create new processes) and DeviceManager (the right to enumerate and claim devices). It can delegate subsets of these to child supervisors.

// init/src/main.rs — this IS the system configuration

fn main(caps: CapSet) {
    let spawner = caps.get::<ProcessSpawner>("spawner");
    let devices = caps.get::<DeviceManager>("devices");
    let timer = caps.get::<Timer>("timer");
    let console = caps.get::<Console>("console");

    // === Phase 1: Hardware drivers ===

    // Find the NIC
    let nic_device = devices.find("virtio-net")
        .expect("no network device found");

    // Spawn NIC driver — gets ONLY its device's MMIO + IRQ
    let nic_driver = spawner.spawn(SpawnRequest {
        binary: "/sbin/virtio-net",
        caps: caps![
            "device_mmio" => nic_device.mmio(),
            "interrupt"   => nic_device.interrupt(),
            "log"         => console.clone(),
        ],
        restart: RestartPolicy::Always,
    });

    // The driver exports a Nic cap once initialized
    let nic: Cap<Nic> = nic_driver.exported("nic").wait();

    // === Phase 2: Network stack ===

    let net_stack = spawner.spawn(SpawnRequest {
        binary: "/sbin/net-stack",
        caps: caps![
            "nic"   => nic,
            "timer" => timer.clone(),
            "log"   => console.clone(),
        ],
        restart: RestartPolicy::Always,
    });

    let net_mgr: Cap<NetworkManager> = net_stack.exported("net").wait();

    // === Phase 3: HTTP service ===

    let tcp = net_mgr.create_tcp_pool();

    let http_service = spawner.spawn(SpawnRequest {
        binary: "/sbin/http-service",
        caps: caps![
            "tcp" => tcp,
            "log" => console.clone(),
        ],
        restart: RestartPolicy::Always,
    });

    let fetch: Cap<Fetch> = http_service.exported("fetch").wait();

    // === Phase 4: Applications ===

    // Trusted telemetry agent — gets full Fetch
    spawner.spawn(SpawnRequest {
        binary: "/sbin/telemetry",
        caps: caps![
            "fetch" => fetch.clone(),
            "log"   => console.clone(),
        ],
        restart: RestartPolicy::OnFailure,
    });

    // Sandboxed app — gets scoped HttpEndpoint
    let api_cap = fetch.attenuate(EndpointPolicy {
        origin: "https://api.example.com",
        paths: Some("/v1/users/*"),
        methods: Some(&["GET", "POST"]),
    });

    spawner.spawn(SpawnRequest {
        binary: "/app/my-service",
        caps: caps![
            "api" => api_cap,
            "log" => console.clone(),
        ],
        restart: RestartPolicy::OnFailure,
    });

    // Init stays alive as the root supervisor
    supervisor_loop(&spawner);
}

Key Mechanisms

Cap export. A spawned process can export capabilities back to its parent via the ProcessHandle (see Spawn Mechanism section). This is how the NIC driver makes its Nic cap available to the network stack — init spawns the driver, waits for it to export "nic", then passes that cap to the next process.

Restart policy. Encoded in SpawnRequest, enforced by the supervisor loop in the spawning process. When a child exits unexpectedly:

1. Old caps held by the child are automatically revoked (kernel invalidates the process’s cap table on exit)
2. Supervisor re-spawns with the same SpawnRequest
3. New instance gets fresh caps — same authority, new identity

Dependency ordering. Sequential in code: wait() on exported caps blocks until the dependency is ready. No declarative dependency graph needed — Rust’s control flow is the dependency graph.

Service Taxonomy

Concrete categories of userspace services capOS expects to run. All spawned by init (or a supervisor init delegates to) after Stage 6. None are pre-init.

Hardware Drivers

One process per managed device. Each holds exactly the caps for its own hardware: an DeviceMmio slice, the corresponding Interrupt cap, and optionally a DmaRegion cap carved out of the frame allocator. Exports a typed device cap (Nic, BlockDevice, Framebuffer, Gpu, …). Examples: virtio-net, virtio-blk, NVMe, AHCI, framebuffer/GPU.

Platform Services

• Logger / journal — accepts Log cap writes, forwards to console and/or durable storage. Init and kernel bootstrap use a direct Console cap until the logger is up; afterwards new services get Log caps only.
• Filesystem — one per mounted volume. Consumes a BlockDevice cap, exports Directory / File caps. FAT, ext4, overlay, tmpfs.
• Store — capability-native content-addressed storage backing persistent capability state (storage-and-naming-proposal.md).
• Network stack — userspace TCP/IP (networking-proposal.md). Consumes Nic + Timer, exports NetworkManager, TcpSocket, UdpSocket, TcpListener.
• DNS resolver — consumes a UdpSocket, exports Resolver.
• Config / secrets store — reads the initial config from BootPackage, exposes runtime Config and Secret caps with per-key attenuation.
• Cloud metadata agent — detects IMDS / ConfigDrive / SMBIOS on cloud boot and delivers a ManifestDelta (cloud-metadata-proposal.md).
• Upgrade manager — orchestrates CapRetarget for live service replacement (live-upgrade-proposal.md).
• Capability proxy — makes selected local caps reachable over the network. The near-term shape is typed Cap’n Proto RPC or a schema-framed proxy, following Cloudflare’s production pattern of schema-bundled Workers bindings to internal services; later remote-capability sessions can borrow Spritely/OCapN CapTP’s session, handoff, and reference-lifetime model without treating current OCapN drafts as capOS ABI commitments. The proxy must never serialize local CapId values, endpoint generations, receiver selectors, or kernel/session ids as portable authority, and it must own explicit resource ledgers for remote refs, queued calls, streams, and retries. See Cloudflare, Cap’n Proto, Workers RPC, and Cap’n Web and Spritely, OCapN, and CapTP.
• Measurement / attestation agent — consumes sealed kernel hashes from BootPackage, exposes Quote caps for remote attestation.

Supervisors

Per-subsystem restart managers that hold a narrowed ProcessSpawner plus the caps of the subtree they own. If any child crashes, the supervisor tears down and re-spawns the set. Example: net-supervisor owns NIC driver + net-stack + DHCP client.

Application Services

User-facing or user-spawned processes: HTTP servers, API gateways, worker pools, shells, interactive tools. Hold only the narrow caps the supervisor grants (HttpEndpoint for one origin, Directory for one mount, etc.). Human users, service accounts, guests, and anonymous callers are represented by session/profile services that grant scoped cap bundles; they are not kernel subjects or ambient process credentials. See User Identity and Policy.

What Does Not Become a Service

• Console / serial — stays in the kernel as a CapObject wrapper. Small enough, needed for kernel diagnostics, no benefit from userspace isolation. A userspace log service can layer on top.
• Frame allocator, virtual memory, scheduler, ring dispatch — kernel primitives, exposed as caps but not as services.
• Interrupt delivery, DMA mapping — kernel mechanisms, exposed to drivers as caps.
• Boot measurement — if added, happens in the kernel before BootPackage exists; the measurement agent (userspace) only reports them.

Supervision

Supervision Tree

Init doesn’t have to supervise everything directly. It can delegate:

init (root supervisor)
  ├─ net-supervisor (holds: spawner subset, device caps)
  │    ├─ virtio-net driver
  │    ├─ net-stack
  │    └─ http-service
  └─ app-supervisor (holds: spawner subset, service caps)
       ├─ my-service
       └─ another-app

Each supervisor is a process that holds a ProcessSpawner cap (possibly restricted to specific binaries) and the caps it needs to grant to children. If net-supervisor crashes, init restarts it, and it re-spawns the entire networking subtree.

Supervisor Loop

#![allow(unused)]
fn main() {
fn supervisor_loop(children: &[SpawnRequest], spawner: &ProcessSpawner) {
    let mut handles: Vec<ProcessHandle> = children.iter()
        .map(|req| spawner.spawn(req.clone()))
        .collect();

    loop {
        // Wait for any child to exit
        let (index, exit_code) = wait_any(&handles);
        let req = &children[index];

        match req.restart {
            RestartPolicy::Always => {
                handles[index] = spawner.spawn(req.clone());
            }
            RestartPolicy::OnFailure if exit_code != 0 => {
                handles[index] = spawner.spawn(req.clone());
            }
            _ => {
                // Process exited normally, don't restart
            }
        }
    }
}
}

Socket Activation

systemd pre-creates a socket and passes the fd to the service on first connection. In capOS, the supervisor does the same with caps:

Eager (default): supervisor spawns the child immediately with a TcpListener cap. Child calls accept() and blocks.

Lazy: supervisor holds the TcpListener cap itself. On first incoming connection (or on first accept() from a proxy cap), it spawns the child and transfers the cap. The child code is identical in both cases.

#![allow(unused)]
fn main() {
// Lazy activation — supervisor holds the listener until needed
let listener = net_mgr.create_tcp_listener();
listener.bind([0,0,0,0], 8080);

// This blocks until a connection arrives
let _conn = listener.accept();

// Now spawn the actual service, giving it the listener
spawner.spawn(SpawnRequest {
    binary: "/app/web-server",
    caps: caps!["listener" => listener, "log" => console.clone()],
    restart: RestartPolicy::Always,
});
}

Configuration

See Storage and Naming for the full storage, naming, and configuration model.

Summary: the system topology is currently defined in a capnp-encoded system manifest baked into the boot image. tools/mkmanifest compiles the human-authored system.cue, system-smoke.cue, or focused manifest sources such as system-spawn.cue, system-devicemmio-grant.cue, and system-wasi-random.cue into the binary manifest. Default boot uses standalone init and init-owned service-graph execution; focused shell-led manifests still grant login/session/broker caps directly to capos-shell for narrow smokes. Focused init-executor manifests let the separate init binary validate and execute the manifest through ProcessSpawner; the old generic kernel resolver has been replaced by first-service cap construction. Manifest-declared SpawnGrantSource::Kernel entries cover the bounded DDF authority surface (DeviceMmio, DMAPool, Interrupt, HardwareAuditLog) and the wasm-host’s optional EntropySource grant; the WASI host adapter (see WASI Host Adapter) and the POSIX adapter (see POSIX Adapter) both run as ordinary userspace processes spawned through this same path. Remaining cleanup is to move runtime configuration into a capability-based store service once that service exists. See also the layered CUE configuration model in System Configuration and Operator Extensibility.

Comparison with Traditional Approaches

Spawn Mechanism

Spawning is a capability-gated operation. The kernel provides a ProcessSpawner capability — only the holder can create new processes.

Implemented Kernel Slice

The kernel now provides:

1. ProcessSpawner capability — a CapObject impl in kernel/src/cap/process_spawner.rs. Methods:

   • spawn(name, binaryName, grants) -> handleIndex — resolve a boot-package binary, load ELF, create address space (builds on existing elf.rs loader and AddressSpace::new_user() in mem/paging.rs), populate the initial cap table, schedule the process, and return the ProcessHandle through the ring result-cap list
   • the returned ProcessHandle cap lets the parent wait for child exit in the first slice; exported caps and kill semantics are later lifecycle work

2. Initial cap passing — at spawn time, the kernel copies permitted parent cap references into the child’s cap table or mints authorized child-local kernel caps. Raw grants preserve the source legacy badge. Endpoint-client grants may mint a requested legacy badge only from an endpoint owner or trusted parent endpoint result source; delegated client facets must preserve their existing service identity. Child-local Endpoint, FrameAllocator, and VirtualMemory grants are created for the child’s process. Child-local endpoint grants return parent-side client facets as result caps instead of sharing the endpoint owner object. The parent’s references are unaffected. Legacy endpoint badges are transitional; new multi-client service identity should use session-bound invocation context plus broker-granted service roots/facets.

3. Cap export — future lifecycle work will let a child register a cap by name in its ProcessHandle, making it available to the parent (or anyone holding the handle). This is the mechanism behind nic_driver.exported("nic").wait() once exported-cap lookup is added.

Schema

interface ProcessSpawner {
    spawn @0 (name :Text, binaryName :Text, grants :List(CapGrant)) -> (
        handleIndex :UInt16,
        capabilityManagerIndex :UInt16,
    );
    createPipe @1 (bufferBytes :UInt32) -> (readIndex :UInt16, writeIndex :UInt16);
}

struct CapGrant {
    name @0 :Text;
    capId @1 :UInt32;
    interfaceId @2 :UInt64;
    mode @3 :CapGrantMode;
    badge @4 :UInt64;
    source @5 :CapGrantSource;
}

struct CapGrantSource {
    union {
        capability @0 :Void;
        kernel @1 :KernelCapSource;
    }
}

enum CapGrantMode {
    raw @0;
    clientEndpoint @1;
    move @2;
    serviceObject @3;
}

interface ProcessHandle {
    wait @0 () -> (exitCode :Int64);
    terminate @1 () -> ();
}

Note on capability passing: Capabilities are referenced by cap table slot IDs (UInt32), not by Cap’n Proto’s native capability table mechanism. spawn() returns the ProcessHandle and a CapabilityManager cap through the ring result-cap list; handleIndex and capabilityManagerIndex identify those transferred caps in the completion. The first slice passes a boot-package binaryName instead of raw ELF bytes so the request stays within the bounded ring parameter buffer. terminate (deferred kill) is implemented on ProcessHandle; post-spawn grants and exported-cap lookup remain future lifecycle work until their authority semantics are implemented. capOS uses manual capnp dispatch (CapObject trait with raw message bytes, not capnp-rpc), so cap references are plain integers and typed result caps use the ring transfer-result metadata. See Userspace Binaries Part 7 for the surrounding userspace bootstrap schema context, Part 4 for the POSIX adapter surface that consumes ProcessSpawner.createPipe plus the recording-shim fork-for-exec successor posix_spawn over the same Move-grant path, and Part 5 for the WASI host adapter that runs as a userspace process spawned through this same ProcessSpawner with manifest-supplied capability grants (WASI Host Adapter).

Relationship to Existing Code

The current kernel has these pieces in place:

• ELF loading (kernel/src/elf.rs) — parses PT_LOAD segments, validates alignment, and feeds the reusable spawn primitive behind ProcessSpawner.
• Address space creation (kernel/src/mem/paging.rs) — AddressSpace::new_user() creates isolated page tables with the kernel mapped in the upper half.
• Cap table (kernel/src/cap/table.rs) — CapTable with insert(), get(), remove(), transfer preflight, provisional insert, commit, and rollback helpers. Each Process owns one local table.
• Process struct and scheduler (kernel/src/process.rs, kernel/src/sched.rs) — a process table plus round-robin run queue are in place for both legacy manifest-spawned services and init-spawned children.

Generic capability transfer/release and the reusable ProcessSpawner lifecycle path are complete enough for the focused init-owned spawn executor. Default startup now uses standalone init for service-graph execution, while focused shell-led startup remains for narrow smokes. ProcessSpawner.createPipe extends the lifecycle surface with a bounded SPSC kernel Pipe capability consumed by the POSIX adapter’s recording-shim fork-for-exec path (P1.3) and exposed as the posix_spawn successor on the same Move-grant path. The DDF Task 5 grant-source families (devicemmio_grant_source.rs, dmapool_grant_source.rs, and their interrupt/audit peers) extend SpawnGrantSource::Kernel with the bounded manager-issued DDF authority surface; production handle lifecycle, hardware- backed driver wait/ack dispatch beyond bounded route proofs, and the S.11.2 hostile-smoke gates remain open. Each spawned process also receives one immutable session context (default-inherited from the parent or broker-selected), used as the invocation subject for audit attribution and the identity-policy boundary. Remaining lifecycle gaps are post-spawn grants, runtime exported-cap lookup, restart supervision, and shrinking the transitional manifest schema. ProcessHandle.terminate (deferred kill) is implemented.

Prerequisites

This proposal describes the target architecture. Individual pieces (like Fetch/HttpEndpoint) are additive — they’re userspace processes that compose existing caps into higher-level ones. No kernel changes needed beyond Stages 4-6.

First Step After Transfer and ProcessSpawner — done 2026-04-23

The minimal demonstration of this architecture landed together with capability transfer and ProcessSpawner:

1. ProcessSpawner cap in kernel/src/cap/process_spawner.rs wraps ELF loading and address-space creation behind a typed capability.
2. Init spawns children — focused make run-spawn boots a single-init manifest; the kernel boots only the separate init binary from initConfig.init, then init spawns the focused demo graph from initConfig.services through ProcessSpawner, grants child-local endpoint owners and client facets, then releases parent endpoint facets before waiting on each ProcessHandle.
3. Cross-process cap invocation — spawned client invokes the server’s Endpoint cap, server replies, both print to console.

This exercises: spawn cap, initial cap passing, manifest-declared export recording, cross-process cap invocation, hostile-input rejection, and per-process resource exhaustion paths. Deleting the unused legacy kernel resolver is post-milestone cleanup tracked in docs/tasks/.

Open Questions

1. Restart supervision. Epoch-based cap revocation and generation-tagged stale reference detection are implemented for current grant/revoke flows. Restart policy still needs a supervisor contract that epoch-bumps caps served by the failed process, restarts from the manifest, and reconnects clients through explicit authority rather than ambient service lookup.

2. Cap discovery. How does a process learn what caps it was given? Resolved: name→(cap_id, interface_id) mapping passed at spawn via a well-known page (CapSet). See Userspace Binaries Part 2. cap_id is the authority-bearing table handle. interface_id is the transported capnp TYPE_ID used by typed clients to check that the handle speaks the expected interface.

3. Lazy spawning. Should the init process start everything eagerly, or should caps be backed by lazy proxies that spawn the backing service on first invocation?

4. Cap persistence. If the system reboots, should the cap graph be reconstructable from saved state? Or is it always rebuilt from init code?

5. Delegation depth. Can an application further delegate its HttpEndpoint cap to a subprocess? If so, the HTTP gateway needs to support fan-out. If not, how is this restriction enforced?