System Architecture
Six problems show up the moment you put agents in front of a real codebase. ostk's architecture is the composition that solves them. Each section below names a problem, walks the composition that addresses it, and points at the primitives that compose.
For the verb-by-verb surface, run ostk help or ostk abi list. For normative spec text, see docs/spec/llmos-posix-kernel.md. This page is the operator's reading guide — what composes into what.
Your daemon crashes while an agent is working. What happens to the work?
Durable project registries rebuild from their local JSONL sources. Anchored ostk-managed sessions write a best-effort drain snapshot after completed turns, and eligible sessions can rehydrate from a compatible snapshot after restart. Work after the last snapshot, runtime-only state, and sessions owned by an external harness are not covered by that promise; client reconnection also depends on the harness.
.ostk/journal.jsonl (WAL) · drain snapshots · Connection Continuity (invariant X) · Anchor Exclusivity (VIII).
Source: src/util/audit.rs, src/serve/server.rs, src/kernel/drain.rs.
An agent gets creative and writes outside its lane. Then what?
Three layers compose for kernel-launched work. Pin caps check fs_ops and bash calls routed through the kernel. The OS sandbox can add Landlock restrictions on Linux or Seatbelt restrictions on macOS when that platform and launch path support them. Bypass detection reports external file changes when the kernel next observes them; it does not retroactively prevent a native client write.
Source: src/serve/policy.rs, src/kernel/sandbox.rs, src/serve/tools/fs_ops.rs.
You need to prove what an agent did, not just trust the log.
The journal is an authoritative source for supported audit-derived registries and projections. Kernel-mediated dispatch rows are append-only and carry the hash of the previous row. When a signing key is available they are also Ed25519-signed; otherwise the signature field remains empty and visibly unverified. Replay rebuilds supported state from local sources, not every byte of session runtime or every derived index.
prev_hash) → optional Ed25519 signature (sig) → rebuild supported registries and projections. Owned State (II) binds daemon authority; Anchor Exclusivity (VIII) prevents two daemon anchors from writing independently.
Source: src/util/audit.rs, src/kernel/signing.rs.
Two agents edit the same file at the same time. Who wins?
A stale fs_ops CAS edit sees the conflict instead of silently overwriting current content. The edit supplies expected text; generation history and the current file let ostk auto-merge safe non-overlapping changes, suggest a nearby merge, or fail for review. Native client writes, raw shell writes, and overwrite-style operations do not inherit this CAS guarantee.
Source: src/kernel/cas.rs, src/kernel/hotpr.rs, src/serve/tools/fs_ops.rs.
You want to hand your agent setup to a different operator and have it just run.
application/v1 is a design trajectory for packaging an agent system as a content-addressed, signed directory with declared capabilities and supervisor metadata. It is not currently a shipped, acceptance-tested cross-machine install workflow. Today, portable claims should be limited to the specific bail/export and integration paths that have their own verification evidence.
"I can hand you my application as a signed file. You install it. You start it. It runs. When it finishes, I can verify what happened against the audit chain you publish." — application/v1 §1
Source: docs/spec/llmos-application.md v0.1, src/commands/app/.
You want to see what every agent did, in real time, without writing pollers or running queries.
The kernel writes the journal; supported indexers consume its rows and project selected state at stable VFS paths. A client can query those projections without maintaining its own polling loop. Rebuild coverage is projection-specific: project registries recover from local JSONL, while commit-graph and embedding artifacts currently have separate or incomplete rebuild paths.
dispatch::fire · VFS namespace projections · forthcoming kernel::registry typed read API (EPIC →1652).
Source: docs/spec/llmos-observation-substrate.md, src/kernel/graph/indexer/, src/kernel/vfs/namespace.rs.
Six problems, one shape.
Each answer above composes a few primitives against a clear failure mode. The substrate makes supported project state queryable, the daemon makes it long-lived, the ABI makes it agent-callable, and drivers extend it. Portability remains integration-specific: current bails, provider routes, MCP clients, and the proposed application/v1 do not share one blanket support status.
What you don't have to know: which file holds which counter, which subsystem listens on which signal, which invariant is implemented in which phase. Those live in the kernel and the spec. The architecture is the composition story above; the rest is implementation.
The ten invariants in full normative form. RFC 2119 keywords. Phase-by-phase rollout map.
Audit ring, subscriber dispatch, VFS namespace contract.
Signed manifest schema, claim graph, supervisor vocabulary, lifecycle verbs.
Inbound bridge for external clients; outbound proxy for ostk-driven agents.
The Five Foundational Laws
These principles describe the architecture ostk is trying to preserve. They guide design review, while each implementation claim still needs a named execution scope, maturity level, and verification path.
The project surface stays familiar
Supported clients keep their normal UI while routing audited reads, CAS edits, and shell calls through ostk. Native client tools are not silently intercepted and remain outside kernel audit and OCC.
Durable state outlives a process
Agents crash, hit context limits, or get killed. Canonical project records live on disk, and anchored ostk-managed sessions write best-effort drain snapshots at completed turn boundaries. In-flight runtime state and external harness sessions have separate recovery boundaries.
Coordinate through the filesystem
Durable tasks, decisions, nudges, and handoff records live in inspectable local files. The daemon and VFS can expose live coordination surfaces, but canonical project records do not depend on a hosted message bus.
Optimistic concurrency
Kernel-mediated CAS edits do not hold a long-lived file lock. They combine expected text with generation history, auto-merge safe non-overlapping changes, and fail visibly when intent is ambiguous. Native and raw-shell writes use ordinary filesystem and Git coordination.
Infrastructure should stay inspectable
Install, init, and boot are short commands, while HUMANFILE, Agentfiles, pin caps, and MCP configuration make important boundaries explicit. The project substrate is readable on disk instead of hidden behind a hosted dashboard.
The Unix Substrate
The ostk kernel does not reinvent basic filesystem primitives. Instead, it relies on battle-tested Unix system calls as its foundational substrate:
rename(2) Atomic file replacement (write to temp + fsync + rename) ensuring no torn writes flock(2) Acquires exclusive locks on critical sections for CAS database commits fsync(2) Enforces durability by flushing buffers to physical disk before renaming O_APPEND Performs lockless audit log appends guaranteed atomic by the OS kernel under PIPE_BUF stat(2) Inspects file modification times (mtime) as a lightweight heartbeat for agent liveness O_CREAT | O_EXCL Creates files exclusively to manage coordination locks safely The Seven Core Primitives
These seven architectural layers build upon the Unix substrate to enable safe, multi-agent operations:
atomic_write gen + CAS Hot PR audit log identity digest injection 304 elision The LLM Memory Hierarchy
We map classical computer memory components to LLM inference structures, optimizing both cost and speed:
Some model endpoints, notably Anthropic, can reuse byte-identical prompt prefixes across compatible requests. The benefit depends on provider cache semantics, account scope, request shape, and model version; Needle Bench reports it per tested model and harness rather than as a universal fleet saving.
The Dual-CPU Scheduler
ostk views humans and LLMs as two distinct execution resources. The CpuDriver trait abstracts this boundary—allowing the kernel to route commands without needing to know whether it communicates with a TTY or an API: