Coconut OS
github →
← back to overview/spec § 02 · what

One ISO. Two install profiles. Six layers.

The kernel is a hard fork of Linux 6.12 LTS. Five existing subsystems get capability-aware modifications; three new subsystems get added. The userspace replaces systemd with coconutd. The shell is a Wayland compositor in Rust.

§ 02.1 — the stack

Hover any layer. The kernel layer is where the work is.

hover · focus · or tap a row · L0 + L1 are where Coconut OS does its work · L2 already ships

§ 02.2 — inside the kernel fork

Five subsystems modified · three new · one userspace bridge.

linux-6.12-coconut
the kernel · hard fork
modified · capability-aware hooks
new · agent subsystems
syscall surface · userspace bridge
syscalls 472-479 · stable ABI from v1.0
range reserved through LKML at Sprint 1
agent_spawnagent_attestagent_quotaagent_cap_grantagent_cap_revokeagent_cap_presentagent_audit_queryagent_memory_tier
kernel hands off PID 1 →
·
coconutd
PID 1 · agent supervisor · CBOR IPC
modified subsystems carry the hooks · new subsystems carry the agent surface · the syscall API is the contract everything else honors

The fork is intentionally narrow. Existing subsystems get capability-aware hooks; the new subsystems carry the agent surface. Everything above the kernel — coconutd, the shell, the brokers — talks to a stable syscall ABI from v1.0.

§ 02.3 — the agent syscall surface

Eight new syscalls — the full agent API.

agent_spawn
(manifest, cap_set) → aid
agent_attest
(aid) → attestation_chain
agent_quota
(aid, kind, budget) → 0 | -E…
agent_cap_grant
(aid, cap) → 0 | -E…
agent_cap_revoke
(aid, cap) → 0 | -E…
agent_cap_present
(aid, cap) → 0 | -E…
agent_audit_query
(filter) → audit_chain_segment
agent_memory_tier
(aid, tier, request) → addr | -E…

full signatures · error code matrices · ABI commitments land with the LLD drop · syscall range is reserved through LKML at Sprint 1

§ 02.4 — the hot path · agent_spawn

From a libcoconut call to a scheduled AID — six stages, one syscall.

  1. userspace
    libcoconutagent_spawn(manifest, cap_set)
    thin libc wrapper · serializes manifest + caps to CBOR
  2. handoff
    syscall
    syscall tablesys_agent_spawn · #472
    trap into kernel · arg copy · auditable entry point
  3. handoff
    kernel/agent
    spawn dispatcheragent_spawn_dispatch()
    validate manifest sig (Ed25519) · allocate AID · build cap_set
  4. security/coconut
    LSM presentationlsm_coconut_agent_spawn_hook()
    caller holds CAP_AGENT_SPAWN? · subset-of-parent caps check
  5. handoff
    kernel/audit/coconut
    audit appendaudit_chain_append(ev=spawn)
    BLAKE3(prev_head || event) · per-CPU ring · sealer kthread
  6. kernel/sched
    scheduler registersched_register_aid(aid, lane)
    agent gets a fair-share lane · cgroup populated · READY
return
aid (u64) · agent in READY state · cgroup populated
error
-EPERM · -EINVAL · -ENOMEM · -EBUSY · audit row sealed regardless
the canonical agent_spawn path · function-body internals + the cred-shim approach pin in the LLD drop

Capability presentation lives in the syscall hot path. The LSM hook runs before any privileged operation reaches the relevant subsystem — that's the property userspace daemons and eBPF can't give you.

§ 02.5 — the agent state machine

Eight first-class kernel states. Process abstraction can't carry these.

initrunningbranchedterminalSpawningAttestedActiveInference-blockedCap-deniedQuarantinedTerminated-cleanTerminated-revoked
happy pathcap-deny branchexit
eight first-class kernel states · canonical transitions shown · the full edge graph + transition guards land with the LLD drop

A process abstraction cannot express "the agent is alive but its capability set just got revoked". Coconut OS makes these states first-class kernel state, visible via agent_audit_query and renderable in Coconut Center.

§ 02.6 — /agent · the inspector tree

What /proc is to processes, /agent is to agents.

coconut tree /agent · agentfs inspector
/agent/
├─ live/· every agent currently in a non-terminal state
│ ├─ a:00001/· Dream Team coordinator · the parent
│ │ ├─ status· current state · READY | ACTIVE | INF_BLOCKED | …
│ │ ├─ manifest· spawn-time signed manifest · Ed25519
│ │ ├─ caps· bound capability bundle · readable, append via syscall
│ │ ├─ attestation/· chain JSON · parent AID · authorizer pubkey
│ │ ├─ audit/· per-agent tail of the global chain
│ │ ├─ budget/· cpu · ram · hbm · net · inference_tokens
│ │ └─ children/· delegated sub-agents (a:00002 … a:00031)
│ ├─ a:00017/· child agent · cap_deny event surfaced 2.046s
│ └─ …· 29 more under a:00001
├─ audit/· system-wide tamper-evident chain
│ ├─ chain.log· JSON-lines · BLAKE3-hashed · append-only
│ ├─ head· current chain head (32 bytes) · re-readable
│ ├─ tpm_root· sealed seed · readable only via syscall
│ └─ rotated/· older shards · zstd-compressed
├─ policy/· operator-side cap templates and broker quotas
│ ├─ caps/· named templates (workstation, server, indie-saas)
│ └─ tenants/· per-tenant fair-share lane configs
└─ graveyard/· terminated agents · audit-only retention
└─ a:00000/· system boot agent · terminated-clean
/agent is to agents what /proc is to processes · file formats + ioctl surface pin in the LLD drop

Every agent gets a directory under /agent/live/<aid>/ with status, the bound caps, attestation chain, a per-agent audit tail, the resource budget, and a child registry. Operators read with cat; auditors verify with coconut audit verify.

held back

Transition guards, allowed predecessors per state, the AID-to-PID mapping rule, the cred-shim approach, agentfs file formats, and the ioctl surface are pinned in the LLD. Public preview shows the shape; full mechanism lands with the LLD drop.

← prev · spec § 01
The thesis
The unit of compute is no longer the Unix process. The OS substrate has to be rebuilt around…
next · spec § 03 →
Capabilities, audit chain, attestation
DAC reduced to a compatibility layer. The capability bundle is the primary access-control ob…