Doctrine
This is project doctrine — position, heritage, and direction. For implementation specifications, see /docs/spec/. For the immediate problem ostk solves, see /why/.
An essay on what we are arguing for, what we are not building, what we inherited, and where we are going. Read in any order.
Agents are users of the runtime.
The load-bearing assumption underneath ostk is small and easy to miss: AI coding agents are first-class users of the runtime, and the runtime should treat them as such. Not user-facing simulations of users, not subroutines of a chat session, not customers of an API. Users — the way a person at a terminal is a user, the way a daemon at boot is a user. They have identities. They open files. They write to disk. They survive their own crashes through state the system, not the user, holds for them.
This is a position with consequences. If agents are users, the operating system underneath them owes them what an operating system owes any user: a stable namespace, a predictable concurrency model, an audit trail that records what they did, and capability boundaries that say what they may and may not touch. None of these are agent-specific concepts. We did not invent them; we inherited them from a half-century of systems work and applied them where they had not yet been applied.
The competing position — the one ostk is arguing against — is that an agent is a feature inside an editor, or a wrapper around a model, or a new kind of API client whose lifecycle ends with the HTTP response. That framing produces tools that are easy to ship and hard to reason about. The concrete failure modes — the ones an operator running a fleet of agents actually hits — are catalogued on /why/. Each is a symptom of the same misframing: treating the agent as an ephemeral feature rather than a process the system is responsible for.
ostk takes the opposite turn. We treat the agent as a process, give it an identity, and build the substrate that everything above it composes through. The kernel does not care which model is answering or which editor is driving — it cares about who wrote, what changed, when, and against which version. Once that floor exists, the surface above it can be whatever the operator likes. The substrate is the part we build; the surface is the part we let the rest of the world build, on top of us, without us in the way.
Everything else in this document follows from that single move.
What ostk is not.
A surface as large as “the operating system for AI coding agents” invites being mistaken for several things at once. The fastest way to describe what something is, when it sits in a crowded category, is to draw the boundary against what it is not.
NOT_A_MODEL ostk does not train, fine-tune, or host language models. It composes with configured provider and local-model routes listed in the support matrix. The kernel keeps project tasks, decisions, file generations, and audit independent of one model; provider features and full-conversation continuity still vary by integration.
NOT_AN_EDITOR ostk does not replace your editor, coding agent, or terminal. Supported MCP clients can connect to the same local project substrate through ostk connect; clients that use native tools outside that surface also operate outside ostk audit and OCC guarantees. If a client is not a verified integration, ostk has a TUI of its own.
NOT_A_SAAS ostk has no required hosted control plane. It is local-first by custody: canonical project state and page content remain on local disk. Configured model providers, web and download tools, registrars, updates, outbound drivers, and provider-backed context features can use the network. Anchored Anthropic sessions can make automatic best-effort Anthropic Files copies for context efficiency or cross-host recovery; operational telemetry remains local.
NOT_A_CHAT_WRAPPER The kernel sits below the agent surface, not on top of it. Kernel-mediated reads, CAS edits, shell calls, and coordination operations share one project substrate. Supported clients can keep their existing UI, but native client tools bypass those guarantees; the integration is explicit even when the workflow feels familiar.
NOT_A_BENCHMARK ostk is not a universal model leaderboard. Its benchmark tooling and the separate Needle Bench project test specific model, provider, and harness combinations; those results are evidence for those combinations, not a blanket product promise. The substrate remains the product focus.
NOT_A_DEPLOYMENT_PLATFORM ostk is not Heroku for agents. It coordinates work on a codebase you already own; it does not run that code in a vendor-managed runtime, scale it across regions, or terminate your TLS. Deployment is downstream of the artifact ostk helps you produce.
NOT_A_GIT_REPLACEMENT ostk’s journal is git’s sibling, not its successor. Git tracks committed source. The kernel journal tracks operations routed through ostk, including accepted and refused writes; native client actions remain Git and filesystem concerns. ostk does not ask you to give up Git—it adds a project-local operational ledger.
NOT_A_FRAMEWORK There is no application framework or base class to adopt. External clients connect through MCP and use ostk tools; internal agents use the same kernel surface. Ordinary native writes remain possible, but they are not silently intercepted and do not receive ostk audit or OCC guarantees.
Heritage.
ostk is not without ancestors. Most of what looks novel about the kernel is a recombination of priors that were already in the literature, applied to a domain — language-model agents — that did not exist when the priors were written. Each entry below names a debt, what we took, and where we declined to follow.
Took: namespaces as protocol — if the resource is a path, every tool that reads paths can observe it.
Declined: distribute the file servers across the network. ostk’s namespace is local first; cross-host federation is a separate spec, not a foundational assumption.
Took: the process identity quad — PID, PPID, PGID, SID — as the model for agent supervision. The shape that survived Unix’s second decade is the shape we wanted for ours.
Declined: inherit the syscall surface area. ostk speaks a kernel ABI of its own. The model is POSIX; the bytes on the wire are not.
Took: supervision trees, let-it-crash discipline, and the assumption that processes die routinely. Agents are ephemeral by construction; supervisors restart them; state lives outside the process.
Declined: switch languages. The kernel is Rust because the kernel is a single binary that has to start fast, run safe, and be auditable in one read. We took the discipline; we kept the toolchain.
Took: the doctrine that governed artifacts should be verifiable and that verification should be cheap enough to perform routinely.
Declined: adopt the certificate-issuer chain. Where signing is configured, the kernel uses Ed25519 keys directly and verifies inline. Signing coverage is conditional and unsigned state remains explicit.
Took: deny by default, and the principle that authority is a capability an agent holds, not an identity it merely claims. Pin caps constrain kernel-mediated actions at the tool boundary before they reach disk.
Declined: reach for an object-capability language. The kernel is Rust; capabilities live in policy data, not in the type system. The principle composes; the implementation is conventional.
Took: the publish-subscribe shape. The audit ring is a write-ahead log; subscribers tap it as logical-decoding listeners; projections land at stable paths in the namespace. The substrate is observable without polling and queryable without a separate truth source.
Declined: sit on a relational core. The audit ring is JSONL on disk; the projections are files; the query layer is path-shaped. Postgres taught us the topology, not the storage engine.
Took: single-binary discipline. One install, one binary, one boot. No Python, no Node, no runtime to install before the install. The kernel is a Rust binary that runs on the platform it ships for.
Declined: fork the userland. ostk is a substrate, not a distribution; the userland on top is yours.
Took: content-addressed history. Audit rows carry the hash of the previous row and, when a signing key is available, an Ed25519 signature. Replay rebuilds supported registries and projections from their authoritative local sources; runtime state and some derived indexes have separate recovery paths.
Declined: replace the index. ostk’s journal records what agents did; git’s log records what humans committed. The journal is git’s sibling, not its replacement.
Trajectory.
Direction the project is moving. Each thread carries an explicit maturity label so the reader can tell what is shipped from what is on the horizon.
Observation substrate
IN PROGRESS The audit ring is shipped at v4.5.0. Subscriber dispatch is shipped. The VFS namespace registers atom-, object-, and lattice-level projections of audit rows at stable paths, so an agent reads the live process table by listing a directory and the open work queue by catting a file. The shape is in place; specific projections continue to land. The spec is at docs/spec/llmos-observation-substrate.md inside the kernel repo; the public mirror is in development.
Sovereign substrate
IN PROGRESS The federation layer that lets builders, registrars, and operators verify each other across hosts without a single trust issuer in the middle. The v0.1 specification has been ratified by an internal panel; the public version is in development. Build claims, check claims, layered resolver, and signed manifests are the substrate-level objects. The exit criterion is concrete: no single third party can stop the operator from shipping.
Application v1
IN PROGRESS The unit above the kernel — a content-addressed, signed directory tree with a manifest, supervisor tree, and policy declaration that one operator can install on another operator’s machine and have it just run. The v0.1 specification has been ratified internally; the public version is in development. Lifecycle claims ride the universal claim event; status is a projection over the claim graph rather than a separate state machine.
Distributed coordination
HORIZON Cross-host kernel coordination — multiple operators, multiple machines, the same audit chain semantics across the boundary. The single-host kernel ships ten invariants; the question is which of them survive across hosts unchanged, which require new primitives, and which are redefined. The network model exists in private as a draft, not an implementation. Direction is clear; substance is not yet shipped.
Sovereign CI
HORIZON A logical consequence of the sovereign substrate: continuous integration as a federation of signed builders, each producing claims that any peer can verify independently. The motivating incident is concrete — a single vendor’s billing failure should not be able to stop a release of bytes that already exist. The substrate primitives are designed against that failure mode; the build verb and builder federation that close the loop are open work.
The map is not the territory. Labels above describe the project as of the current release; specific subsystems advance and retreat between releases. The canonical maturity record lives in the changelog and the spec index at /docs/spec/.
The doctrine is short on purpose. The longer documents are downstream of these four claims: that agents are users, that ostk has a clear set of things it is not, that its design borrows openly and declines deliberately, and that what is shipped and what is on the horizon should be readable in the same paragraph without the two getting confused.
For the immediate operator problems the kernel solves, see /why/. For the implementation contracts the kernel makes, see /docs/spec/. The three pages — doctrine, why, spec — form a triangle. Each links to the other two; each speaks in its own register.