capOS Documentation

cap-os.dev documents the current capOS implementation: the implemented operating model, build and boot workflow, runnable demos, architecture, configuration surface, and security and verification boundaries.

capOS is a research operating system where kernel and userspace services are typed Cap’n Proto capabilities invoked through shared-memory rings. The manual focuses on behavior that exists or is directly reviewable in this repository; project plans, proposals, and research notes remain available as archives rather than driving the primary reading path.

The Basic Idea

capOS is an experiment in making an operating system easier to reason about. In familiar operating systems, a program’s power is spread across many mechanisms: system calls, file paths, sockets, process identity, permissions, environment variables, inherited handles, and service-specific protocols. That model is flexible, but it can be hard to answer simple questions: what can this program actually do, who gave it that power, and can that power be passed, revoked, recorded, or moved somewhere else without hidden side effects?

capOS tries a different tradeoff. A program can act only through explicit typed capabilities it already holds. The interface is the permission: instead of giving a broad handle plus a separate rights mask, capOS gives a narrower object with only the methods the caller should have. The same Cap’n Proto schema describes the kernel call, the service call, and the wire format used between processes.

If that approach works, it should make several things more natural: running small services, tools, and future AI agents with least authority, handing a resource from one program to another without accidentally duplicating it, auditing or replaying service traffic, and eventually moving services across persistence or network boundaries without inventing a second permission model. capOS is not a production OS or a Linux replacement; it is a prototype for testing whether those design choices hold together in real runnable code.

Start Here

For a printable current-system reference, use the PDF manual; planning archives and research notes remain on the website.

• What capOS Is describes the implemented system model and the main authority boundaries.
• Current Status lists what works today, what is partial, and what remains future work.
• Build, Boot, and Test gives the commands used to build the ISO, boot QEMU, and run host-side validation.
• Configuration explains operator overlays, host-user tag injection, the tools cache, and schema-aware data conversion.
• Repository Map maps the main subsystems to source files.
• Programming Languages describes current native Rust support and the status of Python, Go, Lua, C/C++, WASI, and POSIX adapters.
• ABI Evolution Policy defines the compatibility rules for schema, ring, bootstrap, and runtime ABI changes.
• First Chat Demo shows the smallest runnable resident-service chat proof and its current single-terminal limits.
• Aurelian Frontier (proof slice) shows the current runnable multi-process slice of the Aurelian Frontier game and its QEMU proof.
• Paperclips Terminal Demo shows a clean-room incremental terminal game running as an ordinary shell-launched process.

Site Map

• System Architecture is the design reference for current behavior: boot, process, capability, runtime, memory, scheduling, IPC, threading, and park behavior.
• Programming Languages summarizes implemented native Rust support and points language-specific future work back to owning proposals.
• Security and Verification is the reviewer path: trust boundaries, validation workflow, trusted inputs, panic inventory, and DMA design.
• Runnable Demos documents the proof paths that exercise the implemented service model.
• Reference and Project Archives keeps planning, proposal, research, and topic-index material available below the manual sections without making it part of the manual PDF.