v1.0 · 2027 Q4github →

Coconut Labs · pre-implementation

Agents as first-class
kernel primitives.

A Linux distribution where every agent gets an AID, a capability bundle, an attestation chain, and a row in the audit log — the same way every process gets a PID today.

Read the thesis↓Browse the spec →

Kernel surface

Linux 6.12 LTS, hard fork

Team

10 engineers · 26 sprints

v1.0 target

2027 Q4

coconut-tail · /var/log/coconut/kernellive

simulation · drawn from docs/05-LLD §9 audit-chain · what `coconut-tail` looks like at first agent spawn

§ 01 — The thesis

Today's operating systems were designed in 1991 for a world where the unit of compute was a Unix process. The agent era needs the substrate rebuilt.

Today

Agents pretend to be processes.

An LLM-driven agent runs as a Python process under the developer's UID. It has full filesystem access, full network egress, the union of every package's capabilities. The OS gives every process a god view and asks userspace to clip it down.

Tomorrow

Agents are kernel objects.

Every agent has an AID, a declared capability bundle bound at spawn, an attestation chain rooted in a signed manifest, a fair-share lane in the scheduler, and a tamper-evident row in the audit chain. Capability presentation is in the syscall hot path.

Path

Hard fork of Linux 6.12 LTS.

Capability-centric replacement of mm/, fs/, cred.c, sched/, cgroup/. New kernel/agent/, kernel/audit/coconut/, security/coconut/. Eight new syscalls. Ten engineers, 26 sprints, v1.0 ships 2027 Q4.

§ 02 — Five things today's stack can't fix incrementally

You can't ptrace your way to an agent OS. These are kernel-side concerns by construction.

Capability sprawl

today › Agent runs as the user's UID. Intended caps: read three files. Actual caps: everything the user can do.

coconut › Capability-mediated access at the syscall layer. An agent without cap.fs.read on a path literally cannot read it — the syscall returns -ECAPABILITY before reaching the VFS.

No first-class audit chain

today › auditd is process-oriented. Correlating an event back to which agent did what with which capability is a userspace cross-join with no integrity guarantees.

coconut › kernel/audit/coconut/ appends every agent-relevant event to a tamper-evident hash chain rooted in TPM-NV. Off-by-N between LSM-denies and audit-events is a release blocker.

Fairness violations across tenants

today › One customer's runaway loop floods the inference broker. Other 199 tenants see p99 latency spike 30×. Platform team writes userspace rate limiters; they leak.

coconut › Fair-share scheduling extended down into the kernel. CPU time, memory bandwidth, PCIe, inference tokens — all keyed on AID, not PID. p99/p50 ≤ 1.5× under 4-tenant flooder load.

Capability vs DAC mismatch

today › Linux carries UID/GID/mode bits and capabilities and SELinux all stacked. Agents don't cluster into UIDs — every agent is its own principal.

coconut › Capability bundle becomes the primary access-control object. DAC reduced to a legacy compat layer for unmodified binaries. The new LSM is the enforcement point.

No first-class agent lifecycle

today › systemd manages services. cgroups manage isolation. Kubernetes manages pods. None know what an agent is, because none speak the language of agent states.

coconut › Spawning · Attested · Active · Inference-blocked · Capability-denied · Quarantined · Terminated-clean · Terminated-revoked. First-class kernel state, query via agent_audit_query.

The natural pushback is "write a userspace daemon plus an LSM plus a cgroup hierarchy and call it done."

The answer is no, for three reasons that compound: capability presentation must be in the syscall hot path, audit-chain integrity requires kernel-side append, and fair-share scheduling requires scheduler-side AID awareness.

— 01-PRD §3.7

§ 03 — Architecture

One ISO. Two install profiles. Six layers, all the way down to the kernel.

Layer

Brand + distribution

↳ ISO build (x86_64 + ARM64, reproducible)
↳ coconutos.org
↳ GPG signing · mirror network
↳ Brand system

Layer

Showcase workloads

↳ Dream Team — 31-agent virtual eng org
↳ Coconut Studio — flagship agent workbench

Layer

Shell + UX

↳ Coconut Shell — Wayland compositor (Rust + Smithay)
↳ Coconut Center · Coconut Terminal · Coconut Display Manager

Layer

Inference substrate

↳ kvwarden — GPU inference broker (CUDA · x86_64)
↳ mlxd — NPU inference broker (MLX · ARM64)

existing Coconut Labs projects · integrated as default brokers

Layer

System userspace

↳ coconutd — PID 1, agent supervisor (replaces systemd)
↳ coconutpkg · coconut-installer · coconutfs-tools · libcoconut

Layer

Kernel

↳ linux-6.12-coconut — hard fork
↳ modified: mm/ · fs/ · kernel/cred.c · kernel/sched/ · kernel/cgroup/
↳ new: kernel/agent/ · kernel/audit/coconut/ · security/coconut/

8 new syscalls: agent_spawn · agent_attest · agent_quota · agent_cap_grant · agent_cap_revoke · agent_cap_present · agent_audit_query · agent_memory_tier

§ 03·5 — From Coconut Labs

Coconut OS isn't a first attempt. It is the OS layer above projects already shipping.

kvwarden

open →

Layer 2 · x86 · CUDA

Tenant-fair GPU inference broker. Show HN 2026-05-12. Cut starver tail 29× vs FIFO at A100 + vLLM 0.19.1.

mlxd

open →

Layer 2 · ARM · MLX

Same fairness thesis on Apple Silicon NPUs. G3 launch 2026-06-09 → 06-16.

Dream Team

open →

Layer 4 · showcase

31-agent virtual engineering organisation. Existing Python codebase, ported to Coconut OS as the v1.0 hero workload.

§ 04 — The agent syscall surface

Eight new syscalls. Tooled to the same standard as ps, top, strace, journalctl.

agent_spawn

(manifest, cap_set) → aid

Create a new agent. Manifest is signature-verified, cap_set is bound at spawn.

agent_attest

(aid) → attestation_chain

Return the attestation chain linking running code to signed manifest and authorizer.

agent_quota

(aid, kind, budget) → 0 | -E…

Set or query the resource budget for an agent: CPU, mem, HBM, network, inference tokens.

agent_cap_grant

(aid, cap) → 0 | -E…

Grant a capability to an agent. Caller must hold CAP_GRANT(cap). All-or-nothing per call.

agent_cap_revoke

(aid, cap) → 0 | -E…

Revoke a capability mid-execution. Pending operations using the cap return -ECAPABILITY.

agent_cap_present

(aid, cap) → 0 | -E…

Present a capability at syscall time. The LSM hook gates every privileged operation.

agent_audit_query

(filter) → audit_chain_segment

Query the tamper-evident audit chain. Filter by aid, time, event type, capability.

agent_memory_tier

(aid, tier, request) → addr | -E…

Allocate from a tier-addressable memory budget: HBM (GPU) · RAM · SSD-extended.

Full LLD lives in docs/05-LLD.md · userspace bindings ship in libcoconut.

§ 04·5 — Pinned from the PRD

An agent in Coconut OS is a kernel-recognized execution context with a unique AID, a declared capability set bound at spawn, an attestation chain linking the running code to a signed manifest, a fair-share lane in the scheduler and the inference broker, a tier-addressable memory budget spanning HBM, RAM and SSD, and an audit footprint — every syscall, every capability use, every resource access recorded with cryptographically chained hashes.

01-PRD § 2.4 — what "agent-as-primitive" means at the OS level

§ 05 — Fifteen minutes from first boot

Maya, the solo AI researcher. A single workstation, a 31-agent swarm, the audit chain proving every action.

·T+0:00

Maya boots Coconut OS for the first time. The installer asks five questions, picks Workstation profile, reboots into Coconut Shell.

·T+0:08

From Coconut Terminal: coconut agent spawn dream-team. Thirty-one agent processes spawn, each with a capability set declared by the workload manifest.

·T+0:08

All 31 agents share the GPU under kvwarden's fair-share policy — enforced by the kernel scheduler, not a userspace daemon.

·T+0:09

Top bar of Coconut Shell shows a live counter of active agents and aggregate token spend. Each agent's class glyph pulses softly.

·T+0:11

One agent attempts to read /home/maya/.ssh/id_ed25519. The kernel denies — no cap.fs.read on ~/.ssh. Returns -ECAPABILITY before VFS.

·T+0:11

Audit chain appends a tamper-evident row, BLAKE3-hashed against the prior chain head. Coconut Center surfaces a desktop notification with a one-click review link.

·T+0:15

Maya has reproduced the hero use-case end-to-end. 15 minutes from completing the installer to observing the capability-deny + audit-notification flow.

§ 06 — Roadmap

12-18 months to v1.0. Then a four-year curve to the default substrate.

2027 Q4

v1.0

x86_64 + NVIDIA · Workstation + Server

· Linux 6.12 hard fork · capability-mediated LSM
· 8 new syscalls · libcoconut userspace bindings
· coconutd PID 1 · coconutpkg · coconut-installer
· Coconut Shell (Wayland · Rust · Smithay)
· kvwarden + mlxd default brokers

2028 Q2

v1.1

ARM64 server-class

· Ampere first-class · NVIDIA Grace optional
· GUI installer for Server profile
· Live kernel patching (non-critical patches)
· HSM-rooted attestation
· Multi-seat · multi-admin RBAC

2028 Q4

v1.2

Apple Silicon · via Asahi bootstrap

· Apple Silicon NPU first-class
· TouchID PAM module
· Cross-arch checkpoint migration

~2029-30

v2.0

Full kernel substrate · ABI break

· Full mm/agent_mm.c page-allocator rewrite
· Full struct cred replacement (DAC-free)
· Federated tenant model (cross-cluster coconutd)

~2031+

v3.0

Formal-verification expansion · the 5-year vision

· Verification scope extends beyond LSM hook
· Default substrate for safe multi-agent AI compute

Hard ABI line between v1.x and v2.0 · manifests written for v1.x carry across all v1.x releases (NFR-042/043).

§ 07 — Who Coconut OS is for

Five personas drive product decisions. The agent-builder, in five shapes.

Maya

Workstation

Solo AI Researcher

My workstation can run a 31-agent swarm and I can prove what each one did.

hardware · RTX 4090 · 64 GB

David

Server

Platform Eng, agentic startup

Multi-tenant agent fairness without me writing the scheduler.

hardware · 4× H100 · 256-core EPYC

Priya

Server

CISO, regulated enterprise pilot

Every agent action is signed, audit-loggable, and capability-bounded.

hardware · On-prem 8× A100 cluster

Sam

Server

Academic CS department

Fair-share GPU between PhD students without manual quota wars.

hardware · Aging multi-GPU cluster

Ren

Server

Indie agent-SaaS hacker

I ship one ISO and my customer-tier isolation is the OS's problem, not mine.

hardware · Rented H100 (hourly)

§ 08 — Status

Pre-implementation. Specs are public. The build starts when the spec set is locked.

Coconut OS does not exist yet. What exists is the full PM artifact suite — PRD, BRD, TFD, HLD, LLD, execution plan, sprint plans, engineering tickets — produced before a single line of OS code is written. The repo publishes alongside the spec lockdown.

00INDEXopen →

Navigation + reading order across the doc suite

01PRDopen →

Product requirements · vision · personas · KPIs

02BRDopen →

Business requirements · TAM · monetization · ROI

03TFDopen →

Technical feasibility · risks · prior art · build-vs-buy

04HLDopen →

High-level design · architecture · data flow · deployment

05LLDopen →

Low-level design · kernel subsystem detail · syscall API