# 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

<!-- capos-pdf-exclude start -->
For a printable current-system reference, use the [PDF manual](manual.pdf);
planning archives and research notes remain on the website.
<!-- capos-pdf-exclude end -->

- [What capOS Is](overview.md) describes the implemented system model and the
  main authority boundaries.
- [Current Status](status.md) lists what works today, what is partial, and what
  remains future work.
- [Build, Boot, and Test](build-run-test.md) gives the commands used to build
  the ISO, boot QEMU, and run host-side validation.
- [Configuration](configuration.md) explains operator overlays, host-user tag
  injection, the tools cache, and schema-aware data conversion.
- [Repository Map](repo-map.md) maps the main subsystems to source files.
- [Programming Languages](programming-languages.md) describes current native
  Rust support and the status of Python, Go, Lua, C/C++, WASI, and POSIX
  adapters.
- [ABI Evolution Policy](abi-evolution-policy.md) defines the compatibility
  rules for schema, ring, bootstrap, and runtime ABI changes.
- [First Chat Demo](demos/chat.md) shows the smallest runnable resident-service
  chat proof and its current single-terminal limits.
- [Aurelian Frontier (proof slice)](demos/adventure.md) shows the current
  runnable multi-process slice of the Aurelian Frontier game and its QEMU
  proof.
- [Paperclips Terminal Demo](demos/paperclips.md) 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.