# ostk

> A local-first-by-custody project-state layer for AI coding agents. Canonical tasks, decisions, context pages, file generations, and audit remain on disk under your control. Supported MCP clients and configured model routes can work against that same substrate.

ostk's audit, capability, and OCC guarantees apply to operations routed through the kernel. Kernel dispatch rows are hash-chained and are Ed25519-signed when a signing key is available; native client tools bypass those guarantees. CAS conflict handling applies to fs_ops edits that provide expected text, not every filesystem write.

ostk requires no hosted ostk control plane, but local-first does not mean zero network activity. Configured model providers, web/download tools, updates, registrars, outbound drivers, and provider-backed context features can use the network. Anchored Anthropic sessions can automatically make best-effort Anthropic Files copies of drains or context pages for efficiency and cross-host recovery; canonical local content and provider-neutral inline loading remain available without those copies.

## Start here

- [Home](https://ostk.ai/): one-page overview — like containers, for AI agents, plus the kernel underneath
- [Why ostk](https://ostk.ai/why/): the three things that break with multi-agent (collide, drift, leave no trace) and how ostk fixes them
- [Start — pick your path](https://ostk.ai/start/): four modular ways to adopt ostk — userspace sandbox library (libostk), prompt cache proxy (ostk-cache), memory engine (ostk-recall), or the full supervisor CLI suite (ostk)
- [Local model TUI](https://ostk.ai/start/local/): run the CLI agent on your machine via Apple mlx or ollama, with ostk's terminal UI
- [Server mode](https://ostk.ai/start/server/): run the CLI kernel as a daemon for CI runners, remote hosts, and bots
- [Install](https://ostk.ai/install.sh): one-shot curl installer for macOS / Linux

## Docs

- [Documentation index](https://ostk.ai/docs/): full archive of operator and reference docs
- [Downloads](https://ostk.ai/docs/downloads/): signed binaries for macOS and Linux (arm64 + x86_64), curl install with GPG verify, or cargo from source
- [How-to: Learn a sandbox policy](https://ostk.ai/docs/how-to/learn-sandbox/): use `ostk learn` to observe agent filesystem access and auto-generate LIMIT sandbox directives
- [FAQ](https://ostk.ai/docs/faq/): frequently asked questions — coordination, install, trust tiers, secrets, crash recovery

### Modular Stack
- [ostk (Kernel)](https://ostk.ai/docs/ostk/): optimistic concurrency daemon and terminal interface
- [ostk-recall (Memory)](https://ostk.ai/docs/ostk-recall/): autonomous memory and context indexing MCP server
- [ostk-cache (Proxy)](https://ostk.ai/docs/ostk-cache/): drop-in LLM proxy with multi-tier prompt compression
- [libostk (Client)](https://ostk.ai/docs/libostk/): userspace client library with JSON-RPC interface

### Reference
- [Commands](https://ostk.ai/docs/commands/): every CLI verb — stable agent-callable System ABI plus the operator overlay, with worked examples
- [System architecture](https://ostk.ai/docs/architecture/): how ostk's primitives compose to solve crash recovery, agent containment, write coordination, verifiable history, portable deployment, and observation (also incorporates five-laws and kernel-spec)
- [Agent lifecycle](https://ostk.ai/docs/agent-lifecycle/): five states, context-pressure thresholds, drain snapshots, graceful-then-forced kill, ephemeral-by-design (incorporates session-topology)
- [Context management](https://ostk.ai/docs/context-management/): preload render, prompt cache, digest envelope, 304 elision, context pressure handoff, drain snapshots (incorporates compression, enrichment, pull-model, and skills)
- [Coordination primitives](https://ostk.ai/docs/coordination-primitives/): four primitives that let multiple agents share a codebase without a message bus (incorporates vfs)
- [MCP integration](https://ostk.ai/docs/mcp/): bidirectional MCP — inbound (your agent drives ostk) and outbound (ostk-driven agents call external MCP services)
- [Models](https://ostk.ai/docs/models/): supported LLM providers, driver feature exposure, model selection (HUMANFILE, FROM auto, OSTK_MODEL)
- [Needles](https://ostk.ai/docs/needles/): the atomic work item — storage format, lifecycle, hay capture, compile pipeline, spheres, compounds, dependency edges
- [Sphere navigator](https://ostk.ai/docs/sphere-navigator/): TUI overlay for the needle dependency graph — four view levels from Galaxy to NeedleDetail
- [Tack grammar](https://ostk.ai/docs/tack-grammar/): operator intent language for the TUI tack bar — compressed input that resolves through the kernel
- [TUI](https://ostk.ai/docs/tui/): terminal interface guide — panes, keyboard shortcuts, tack grammar, approval modals, capture
- [Specifications index](https://ostk.ai/docs/spec/): specifications index for kernel internals, trust, coordination, and application layers
- [POSIX kernel spec](https://ostk.ai/docs/spec/posix-kernel/): RFC-style specification of the POSIX-shaped invariants enforced by the kernel

### Configuration & Governance
- [Configuration reference](https://ostk.ai/docs/configuration/): reference for HUMANFILE, ENTITYFILE, .primefile, ostk.toml, and environment variables
- [Agentfile](https://ostk.ai/docs/agentfile/): a Dockerfile for agents — declarative spec the kernel can audit, supervise, and verify
- [Security & Trust](https://ostk.ai/docs/security/): GPG identity tiers, capability pins, verifiable audits, secrets, and signed bundles (incorporates trust-model, pins, approval-chain, isolation-tiers, secrets, and bail)

## Optional

- [About](https://ostk.ai/about/): project background — distributed OS for AI coding agents, Unix-inspired, local-first, invisible by design
- [llms-full.txt](https://ostk.ai/llms-full.txt): the full text of every page above concatenated, designed for LLM context windows