The root README is the product overview and fastest path to a running Astra instance. This index routes users, application developers, operators, and kernel contributors to the level of detail they need.
Important
Quickstarts, guides, and references describe supported implementation paths.
Documents in design/ are normative target contracts and may be
ahead of the implementation on a given branch. Code, contract tests, and
runtime-profile tests remain authoritative for current behavior.
| Goal | Start here | Next |
|---|---|---|
| Evaluate or use Astra | Getting started | CLI reference, TUI slash commands, configuration |
| Build a product on Astra | TypeScript SDK | HTTP API, configuration |
| Deploy and operate Astra | Deployment overview | Docker, production, troubleshooting |
| Develop or contribute | Developer setup | Development workflow, testing, Make targets |
| Understand or extend the kernel | Architecture | Design index and the core reading path below |
| Document | What it covers |
|---|---|
| Quick start | Source and Docker entry points, first health check, and where to go next |
| CLI commands | Authentication, chat, sessions, models, skills, and administration |
| TUI slash commands | Interactive workspace, planning, observability, memory, and MCP commands |
| TypeScript SDK | REST, SSE, WebSocket, React hooks, and browser integration |
| HTTP API | Authentication and server resource contracts |
| Configuration | Models, authentication, Server, User Runner, and observability settings |
| Document | What it covers |
|---|---|
| Deployment overview | Supported deployment shapes and runtime-profile validation |
| Docker quick start | All-in-one Compose and API-container development |
| Production deployment | Required secrets and Server-only or Server + User Runner startup |
| Deployment guide | Recommended operational path and health verification |
| Configuration reference | Server, database, authentication, model, Runner, and observability settings |
| Troubleshooting | First diagnostics for dependencies, server startup, and tests |
| Run projection repair | Repair procedure when a derived run view is stale |
| Document | What it covers |
|---|---|
| Developer setup | Prerequisites, repository layout, local loop, and code conventions |
| Development workflow | Server-only, Server + User Runner, and Docker development profiles |
| Testing guide | Offline, contract, online, and system test lanes |
| Offline router workflow | Approved trace datasets, isolated paired evidence, and offline candidate training |
| Makefile reference | Build, validation, test, and development targets |
| Dependencies | Required and optional development tools |
| Repository automation | Maintainer contract for Mergify, branch protection, and external-fork delivery |
| Release guide | Maintainer workflow for versioned CLI and container releases |
| System E2E matrix | Cross-surface runtime behavior and coverage obligations |
| Capability harness | Capability-provider and model/tool test contract |
| Coverage matrix | Feature-to-test coverage map |
Before changing runtime behavior, read the owning design contract. Run the
narrowest relevant test while iterating, then make check and the applicable
offline or online lane before submitting a change.
Start with Architecture, then use this path according to the subsystem you are changing:
| Concern | Canonical design documents |
|---|---|
| One backbone and runtime profiles | Agent backbone and capacity providers, client surfaces and deployment |
| Durable Work and orchestration | Runtime lifecycle, durable agent runs, orchestration |
| User Runner and hybrid execution | Edge-cloud execution, edge runtime tool boundary, Web agent runner, cloud-edge sync |
| Tools, providers, and policy | Capability system, provider runtime, safety and permissions, tool-result quality firewall |
| Context Pipeline | ContextPipe paper, context and prompt, prompt lifecycle, context-window management, memory |
| Trace, Explain, Introspect, and Reflect | Observation plane, introspect and reflect, session observability, artifacts and debug bundles |
| Models, data, and learning | Model access and inference, data and storage, evaluation and learning, tuning jobs |
The design index is the complete map of design domains and ownership boundaries.
| Directory | Contract |
|---|---|
quickstart/ |
Short, outcome-oriented first-run paths |
guides/ |
Task-oriented procedures, workflows, and runbooks |
reference/ |
Current commands, APIs, configuration, and dependencies |
design/ |
Normative architecture and target behavior |
architecture/ |
Cross-domain architecture views |
testing/ |
Test strategy, matrices, and coverage contracts |
product/ |
Versioned product acceptance baselines; not current user guidance |
- One design domain has one canonical document.
- Describe invariants, responsibilities, state, and failure semantics—not implementation chronology.
- Keep transient plans and verification transcripts out of durable docs.
- Link to a source of truth instead of duplicating it.
- Update the relevant quickstart, guide, or reference whenever a public workflow or interface changes.
- State test obligations for every behavioral design contract.
The governing principle is simple: Astra has one agent backbone and multiple capacity providers. Web, CLI, Server, User Runner, MCP, and future providers share lifecycle, context, policy, trace, reflection, checkpoint, and audit semantics; capability differences come from providers, not separate agent implementations.