# capOS Documentation

> capOS is a research capability operating system whose documentation covers architecture, security, proposals, planning, and runnable proof slices.

## Introduction

- [Introduction](index.md): Top-level book entry.

## Start Here

- [What capOS Is](overview.md): One-page system model.
- [Current Status](status.md): What works, what is partial.
- [Full Documentation](capos-docs.md): Single-page generated documentation bundle.
- [Build, Boot, and Test](build-run-test.md): Build, ISO, QEMU, host-test commands.
- [Configuration](configuration.md): How operators extend the default capOS boot manifest with a gitignored `system.local.cue` overlay and convert CUE-authored data to specified Cap'n Proto schemas. Status: Implemented. Last reviewed: 2026-04-29 13:26 UTC
- [Repository Map](repo-map.md): Source-tree subsystem index.
- [Topics Index](topics.md)

## Runnable Demos

- [First Chat Demo](demos/chat.md): Smallest resident-service proof.
- [Aurelian Frontier (proof slice)](demos/adventure.md): Multi-process Aurelian Frontier smoke proof.
- [Paperclips Terminal Demo](demos/paperclips.md): Clean-room incremental terminal demo.

## System Architecture

- [Boot Flow](architecture/boot-flow.md): Kernel boot, manifest handoff, init launch, and QEMU boot-proof flow. Status: Partially implemented. Last reviewed: 2026-04-28 12:48 UTC
- [Manifest and Service Startup](architecture/manifest-startup.md): Manifest encoding, service graph validation, bootstrap grants, and init-side spawning. Status: Partially implemented. Last reviewed: 2026-04-29 13:26 UTC
- [Process Model](architecture/process-model.md): Process isolation, ELF loading, bootstrap ABI, lifecycle, and spawn authority. Status: Partially implemented. Last reviewed: 2026-04-25 00:08 UTC
- [In-Process Threading](architecture/threading.md): In-process thread lifecycle, scheduler references, ThreadControl, and ParkSpace integration. Status: Partially implemented. Last reviewed: 2026-04-29 11:52 UTC
- [Park Authority](architecture/park.md): ParkSpace wait/wake authority, ABI, and shared park-word constraints. Status: Partially implemented. Last reviewed: 2026-04-29 11:52 UTC
- [Capability Model](capability-model.md): Core capability object model, cap tables, schema interface IDs, grants, receiver metadata, and transfer. Status: Partially implemented. Last reviewed: 2026-04-29 09:14 UTC
- [Capability Ring](architecture/capability-ring.md): Shared-memory capability ring ABI, dispatch paths, and completion semantics. Status: Implemented. Last reviewed: 2026-04-26 21:31 EEST
- [IPC and Endpoints](architecture/ipc-endpoints.md): Endpoint IPC, capability transfer, direct handoff, and shared-memory data paths. Status: Partially implemented. Last reviewed: 2026-04-29 09:14 UTC
- [Authority Accounting](authority-accounting-transfer-design.md): Authority accounting rules for capability transfer and resource charges. Status: Accepted design. Last reviewed: 2026-04-29 11:52 UTC
- [Userspace Runtime](architecture/userspace-runtime.md): capos-rt entry ABI, heap, CapSet lookup, ring client, and typed userspace capability clients. Status: Partially implemented. Last reviewed: 2026-04-26 19:20 EEST
- [Memory Management](architecture/memory.md): Physical frames, address spaces, user buffers, MemoryObject, and VirtualMemory contracts. Status: Partially implemented. Last reviewed: 2026-04-26 19:20 EEST
- [Scheduling](architecture/scheduling.md): Preemption, run queues, blocking waits, timer wakeups, and SMP scheduler proof points. Status: Partially implemented. Last reviewed: 2026-04-29 11:52 UTC

## Security and Verification

- [Trust Boundaries](security/trust-boundaries.md): The reviewer's authority-boundary inventory.
- [Verification Workflow](security/verification-workflow.md): The verification gates used by capOS.
- [Trusted Build Inputs](trusted-build-inputs.md): Trusted toolchain inventory.
- [Panic Surface Inventory](panic-surface-inventory.md): Panic/unwrap/expect inventory.
- [DMA Isolation](dma-isolation-design.md): DMA isolation model for device memory, IOMMU policy, and capability-scoped hardware access. Status: Accepted design. Last reviewed: 2026-04-29 11:52 UTC
- [Design Risks and Open Questions](design-risks-register.md): Consolidated index of long-horizon design risks.

## Planning

- [Roadmap](roadmap.md): Long-term architectural plan.
- [Changelog](changelog.md): Historical milestone reports.
- [Whitepaper Plan](paper/plan.md): Planning baseline for the future schema-as-ABI capOS whitepaper.
- [Whitepaper Outline](paper/outline.md): Section outline and evidence dependency map for the schema-as-ABI capOS whitepaper.
- [Whitepaper Evidence Gaps](paper/evidence-gaps.md): Tracks unresolved whitepaper evidence needs and the milestones that close them. Last reviewed: 2026-04-28 15:09 UTC
- [Backlog](backlog/index.md): Detailed task decompositions.
- [Runtime, Networking, and Shell](backlog/runtime-network-shell.md): Runtime/network/shell backlog.
- [Go VirtualMemory Contract](backlog/go-virtual-memory-contract.md): VirtualMemory cap contract for Go.
- [Session-Bound Invocation Context](backlog/session-bound-invocation-context.md): Implementation plan for one-session-per-process invocation context and session-keyed shared services.
- [Service Object Identity Migration](backlog/service-object-identity-migration.md): Superseded large-chunk migration plan for service object identity, retained as historical context after the active direction changed to session-bound invocation context.
- [Stage 6 Capability Semantics](backlog/stage-6-capability-semantics.md): Stage 6 capability work.
- [SMP Phase C](backlog/smp-phase-c.md): SMP backlog.
- [Security and Verification](backlog/security-verification.md): Security/verification backlog.
- [Hardware, Boot, and Storage](backlog/hardware-boot-storage.md): Hardware bring-up backlog.
- [Local Users, Storage, and Policy](backlog/local-users-management.md): Identity/local-user backlog.
- [Shared-Service Demos](backlog/shared-service-demos.md): Demo backlog.
- [Paperclips Terminal Demo](backlog/paperclips.md): Paperclips terminal demo backlog and content migration notes.
- [Run Targets, Init Mandate, and Default-Run Integration](backlog/run-targets-and-init-policy.md): Run-target governance.
- [Aurelian Frontier](backlog/aurelian-frontier.md): Aurelian Frontier game-depth backlog.

## Design Archive

- [Proposal Index](proposals/index.md): Proposal status table.
- [Service Architecture](proposals/service-architecture-proposal.md): Capability-based service composition, authority-at-spawn, exports, and service graph policy. Status: Partially implemented. Last reviewed: 2026-04-28 15:09 UTC
- [Session-Bound Invocation Context](proposals/session-bound-invocation-context-proposal.md): Session-bound invocation context and privacy-aware disclosure model replacing service-object identity migration. Status: Partially implemented. Last reviewed: 2026-04-29 10:20 UTC
- [Storage and Naming](proposals/storage-and-naming-proposal.md): Capability-native storage, namespaces, boot packages, volumes, and persistence model. Status: Accepted design. Last reviewed: 2026-04-26 03:21 UTC
- [Error Handling](proposals/error-handling-proposal.md): Transport and application error model for capability calls and CQE results. Status: Implemented. Last reviewed: 2026-04-29 11:52 UTC
- [Security and Verification](proposals/security-and-verification-proposal.md): Security review vocabulary, trust-boundary checklist, and verification tracks for capOS. Status: Partially implemented. Last reviewed: 2026-04-29 11:52 UTC
- [capOS Repository Harness Engineering](proposals/capos-repo-harness-engineering-proposal.md): Repository-local harness engineering for making capOS legible, checkable, and safer for long-running coding agents. Status: Future design. Last reviewed: 2026-04-28 00:00 UTC
- [SMP](proposals/smp-proposal.md): Per-CPU state, AP startup, scheduler ownership, TLB shootdown, and multi-core roadmap. Status: Accepted design. Last reviewed: 2026-04-25 11:04 UTC
- [Ring v2 For Full SMP](proposals/ring-v2-smp-proposal.md): Per-thread ring, completion routing, SQPOLL ownership, and full-SMP transport model. Status: Future design. Last reviewed: 2026-04-29 08:40 UTC
- [Tickless and Realtime Scheduling](proposals/tickless-realtime-scheduling-proposal.md): Tickless idle, SQPOLL nohz CPU isolation, request deadlines, scheduling contexts, and realtime islands. Status: Future design. Last reviewed: 2026-04-29 11:52 UTC
- [mdBook Documentation Site](proposals/mdbook-docs-site-proposal.md): Documentation-site structure, metadata, status vocabulary, and curation workflow. Status: Partially implemented. Last reviewed: 2026-04-29 10:36 UTC
- [Networking](proposals/networking-proposal.md): Network capability architecture from virtio-net smoke to TCP sockets and terminal handoff. Status: Partially implemented. Last reviewed: 2026-04-29 08:40 UTC
- [libcapos-service](proposals/libcapos-service-proposal.md): Userspace service framework for lifecycle, endpoint loops, readiness, shutdown, metrics, context, and resource hooks. Status: Future design. Last reviewed: 2026-04-29 11:52 UTC
- [Userspace Binaries](proposals/userspace-binaries-proposal.md): Native userspace binary model, capos-rt authority handling, and language/POSIX support. Status: Partially implemented. Last reviewed: 2026-04-25 13:38 UTC
- [Shell](proposals/shell-proposal.md): Native, agent-oriented, and POSIX shell models over explicit capability grants. Status: Partially implemented. Last reviewed: 2026-04-28 22:02 UTC
- [SSH Shell Gateway](proposals/ssh-shell-proposal.md): SSH terminal gateway design preserving TerminalSession and broker-issued shell boundaries. Status: Partially implemented. Last reviewed: 2026-04-29 11:52 UTC
- [Telnet over TLS Shell](proposals/telnet-tls-shell-proposal.md): TLS-protected Telnet TerminalSession gateway with client certificates and credential fallback. Status: Future design. Last reviewed: 2026-04-29 07:35 UTC
- [Boot to Shell](proposals/boot-to-shell-proposal.md): Login, setup, session, credential, and broker path from boot into the native shell. Status: Partially implemented. Last reviewed: 2026-04-28 21:15 UTC
- [System Info Capability](proposals/system-info-proposal.md): SystemInfo capability for MOTD, host metadata, help topics, and shell bundle integration. Status: Phase 1 + Phase 2 implemented. Last reviewed: 2026-04-29 05:59 UTC
- [Interactive Command Surfaces](proposals/interactive-command-surface-proposal.md): Structured command-session model for native interactive applications over typed invocations. Status: Future design. Last reviewed: 2026-04-29 07:55 UTC
- [Userspace Authority Broker](proposals/userspace-authority-broker-proposal.md): Userspace shell-bundle broker and lifecycle-control authority model. Status: Future design. Last reviewed: 2026-04-26 17:40 EEST
- [Go Runtime](proposals/go-runtime-proposal.md): Go runtime plan for GOOS=capos, memory growth, TLS, scheduling, and networking. Status: Future design. Last reviewed: 2026-04-29 11:52 UTC
- [Lua Scripting](proposals/lua-scripting-proposal.md): Capability-scoped Lua runner with curated libraries and explicit grants. Status: Future design. Last reviewed: 2026-04-25 14:22 UTC
- [Resource Accounting and Quotas](proposals/resource-accounting-proposal.md): Resource profiles, quota ledgers, donation, reservation, and fail-closed accounting semantics. Status: Partially implemented / Future architecture. Last reviewed: 2026-04-29 11:52 UTC
- [OOM Handling and Swap](proposals/oom-and-swap-proposal.md): Memory-pressure, OOM, anonymous-memory budgeting, and optional encrypted swap policy. Status: Future design. Last reviewed: 2026-04-29 11:52 UTC
- [System Monitoring](proposals/system-monitoring-proposal.md): Capability-scoped logs, metrics, health checks, traces, crash records, and status views. Status: Future design. Last reviewed: 2026-04-29 11:52 UTC
- [System Performance Benchmarks](proposals/system-performance-benchmarks-proposal.md): Correctness-gated benchmark model for primitives, workloads, and user stories. Status: Future design. Last reviewed: 2026-04-25 17:50 UTC
- [User Identity and Policy](proposals/user-identity-and-policy-proposal.md): User, session, profile, RBAC/ABAC/MAC, and policy-layer model for capability grants. Status: Partially implemented. Last reviewed: 2026-04-28 21:15 UTC
- [Delegated Subject Context](proposals/delegated-subject-context-proposal.md): Future delegated-subject and act-on-behalf-of capability model. Status: Future design. Last reviewed: 2026-04-28 14:35 UTC
- [System Configuration and Operator Extensibility](proposals/system-configuration-proposal.md): Layered CUE configuration model for operator boot-manifest overlays, host-user injection, and per-user toolchain caches. Status: Partially implemented. Last reviewed: 2026-04-29 13:52 UTC
- [Cryptography and Key Management](proposals/cryptography-and-key-management-proposal.md): Capability model for keys, signing, encryption, vaults, entropy, and cryptographic policy. Status: Future design. Last reviewed: 2026-04-25 19:27 UTC
- [Certificates and TLS](proposals/certificates-and-tls-proposal.md): Capability-native X.509, trust store, ACME, pinning, and TLS configuration model. Status: Future design. Last reviewed: 2026-04-23 13:48 EEST
- [OIDC and OAuth2](proposals/oidc-and-oauth2-proposal.md): Federated login, OAuth2 clients, token capabilities, JWKS, DPoP, and broker integration. Status: Future design. Last reviewed: 2026-04-25 18:03 UTC
- [Volume Encryption](proposals/volume-encryption-proposal.md): Encryption-at-rest model for system and user volumes with recovery and KMS options. Status: Future design. Last reviewed: 2026-04-25 11:50 UTC
- [Cloud Metadata](proposals/cloud-metadata-proposal.md): Cloud metadata and config-drive bootstrap through scoped configuration capabilities. Status: Future design. Last reviewed: 2026-04-23 09:19 UTC
- [Cloud Deployment](proposals/cloud-deployment-proposal.md): Cloud VM deployment plan covering hardware abstraction, storage, networking, and aarch64. Status: Future design. Last reviewed: 2026-04-26 03:21 UTC
- [Live Upgrade](proposals/live-upgrade-proposal.md): Service replacement, capability retargeting, quiesce/resume, and in-flight call handling. Status: Future design. Last reviewed: 2026-04-23 09:19 UTC
- [GPU Capability](proposals/gpu-capability-proposal.md): Capability-oriented GPU access, driver isolation, memory sharing, and CUDA-style compute model. Status: Future design. Last reviewed: 2026-04-23 09:19 UTC
- [capOS As A Robot Brain](proposals/robot-brain-proposal.md): Robotics service graph, actuator gateway, safety monitor, realtime island, and ROS bridge model. Status: Future design. Last reviewed: 2026-04-25 10:35 UTC
- [Formal MAC/MIC](proposals/formal-mac-mic-proposal.md): Formal mandatory access and integrity model for future policy and proof work. Status: Future design. Last reviewed: 2026-04-23 14:20 EEST
- [Browser/WASM](proposals/browser-wasm-proposal.md): Browser-hosted capOS experiment using WebAssembly and worker-per-process isolation. Status: Future design. Last reviewed: 2026-04-23 09:19 UTC
- [Language Models and Agent Runtime](proposals/llm-and-agent-proposal.md): Language-model, embedder, agent-runner, and browser-agent capability interfaces. Status: Future design. Last reviewed: 2026-04-25 11:50 UTC
- [capOS-Hosted Agent Swarms](proposals/hosted-agent-swarm-proposal.md): capOS-hosted OpenClaw-like personal agents, agent swarms, harness controls, memory, retrieval, and research agenda. Status: Future design. Last reviewed: 2026-04-28 00:00 UTC
- [Realtime Voice Agent Shell](proposals/realtime-voice-agent-shell-proposal.md): Realtime audio agent shell model across browser media, provider sessions, and brokered tools. Status: Future design. Last reviewed: 2026-04-29 06:50 UTC
- [Aurelian Frontier](proposals/aurelian-frontier-proposal.md): Capability-native Aurelian Frontier game design, mission model, content pipeline, and QEMU proof slice. Status: Partially implemented. Last reviewed: 2026-04-29 09:18 UTC
- [Contributor Quest Mechanics](proposals/contributor-quest-mechanics-proposal.md): Contributor reward mechanics layered on Aurelian Frontier without granting repository authority. Status: Future design. Last reviewed: 2026-04-25 14:42 UTC
- [Public Release and Maintainer Boundaries](proposals/public-release-boundaries-proposal.md): Public release posture, maintainer boundaries, issue intake, and repository hygiene gates. Status: Future design. Last reviewed: 2026-04-28 12:48 UTC
- [Repository Composition](proposals/repository-composition-proposal.md): Repository scope, sibling project split criteria, and cross-repository organization plan. Status: Future design. Last reviewed: 2026-04-27 15:53 EEST
- [Proposal Group Archive](proposals/other.md): Archived proposal cluster.
- [Rejected: Endpoint Badges as Service Identity](proposals/rejected-endpoint-badges-proposal.md): Post-mortem of the rejected seL4-style endpoint badge service identity model. Status: Rejected. Last reviewed: 2026-04-28 15:55 UTC
- [Superseded: Service Object Capabilities](proposals/service-object-capabilities-proposal.md): Superseded service-minted object capability model that was replaced by session-bound invocation context. Status: Superseded. Last reviewed: 2026-04-28 17:01 UTC
- [Rejected: Cap'n Proto SQE Envelope](proposals/rejected-capnp-ring-sqe-proposal.md): Rationale for keeping ring SQEs fixed-layout instead of Cap'n Proto envelopes. Status: Rejected. Last reviewed: 2026-04-23 09:19 UTC
- [Rejected: Sleep(INF) Process Termination](proposals/rejected-sleep-inf-termination-proposal.md): Rationale for explicit process termination instead of infinite-sleep lifecycle semantics. Status: Rejected. Last reviewed: 2026-04-23 09:19 UTC

## Research and Papers

- [Papers](papers.md): Long-form research write-ups.
- [Research Index](research.md): Design consequences pulled from the survey.
- [seL4](research/sel4.md): Microkernel and capability reference.
- [Zircon](research/zircon.md): Handle-based OS reference.
- [Genode](research/genode.md): Componentized OS framework.
- [Plan 9 and Inferno](research/plan9-inferno.md): Namespace-oriented systems.
- [EROS, CapROS, Coyotos](research/eros-capros-coyotos.md): Persistent capability-system lineage.
- [LLVM Target](research/llvm-target.md): Requirements for a custom LLVM target triple.
- [Out-of-Kernel Scheduling](research/out-of-kernel-scheduling.md): Userspace scheduling prior art.
- [Completion Rings And Threaded Runtimes](research/completion-ring-threading.md): Io_uring-style transports under threaded runtimes.
- [x2APIC And APIC Virtualization](research/x2apic-and-virtualization.md): Interrupt routing on modern x86.
- [NO_HZ, SQPOLL, and Realtime Scheduling](research/nohz-sqpoll-realtime.md): Linux NO_HZ, io_uring SQPOLL, CPU isolation, PREEMPT_RT, SCHED_DEADLINE, and seL4 MCS grounding for capOS timer and realtime design. Status: Research note. Last reviewed: 2026-04-29 06:50 UTC
- [Cap'n Proto Error Handling](research/capnp-error-handling.md): Prior-art on capnp-rpc error semantics.
- [OS Error Handling](research/os-error-handling.md): Cross-OS error-model comparison.
- [IX-on-capOS Hosting](research/ix-on-capos-hosting.md): IX as a package corpus, content-addressed build/store model, and a capability-native build-service surface for capOS.
- [Pingora](research/pingora.md): Proxy/server framework as a userspace runtime case study.
- [Game Mechanics Prior Art](research/game-mechanics-prior-art.md): Grounded mechanics research for Aurelian Frontier seasonal play, markets, construction, and tactical combat. Status: Research note. Last reviewed: 2026-04-29 08:35 UTC
- [Small LLM Survey](research/small-llm-survey.md): Model candidates for the on-ISO local LLM. Last reviewed: 2026-04-24 21:42 EEST
- [Hosted Agent Harnesses](research/hosted-agent-harnesses.md): OpenClaw-like harnesses, swarms, memory/wiki systems, and agent orchestration research for capOS-hosted agents. Status: Research note. Last reviewed: 2026-04-28 00:00 UTC
- [Multimedia Pipeline Latency](research/multimedia-pipeline-latency.md): Research note. Status: Research note. Last reviewed: 2026-04-25 09:32 UTC
- [Realtime Multimodal Agent APIs](research/realtime-multimodal-agent-apis.md): Research note. Status: Research note. Last reviewed: 2026-04-25 09:32 UTC
- [Robotics Realtime Control](research/robotics-realtime-control.md): Research note. Status: Research note. Last reviewed: 2026-04-25 10:35 UTC