Right context. Governed actions. Runners where your IT lives. End-to-end traceability.
Why Astra · Research · Quick start · Architecture · Runner · Comparison · Docs
Astra is an open-source runtime for durable agent work across real enterprise systems. It connects what an agent knows to where its work happens: the Context Pipeline assembles the right information, Policy governs each action, Runners execute inside the environment that owns the tools and data, and Trace records what actually happened.
Context decides what the agent knows. Policy decides what it may do. The Runner carries out the action where the relevant systems live. Trace makes the result explainable and accountable.
Research-backed: Astra's Context Pipeline is presented in ContextPipe: Database-Inspired Context Assembly for Long-Horizon Agents, accepted at ADS 2026, co-located with VLDB 2026.
Note
Astra is under active development and public interfaces may change before
1.0. Documents in docs/design/ define target contracts and
may lead the implementation on a given branch. Current behavior is guarded by
code, contract tests, and runtime-profile tests.
A model plus tools is a useful starting point. Enterprise work adds longer time horizons and fragmented environments: private repositories, internal APIs, databases, local tools, user credentials, approval boundaries, and systems that cannot simply be exposed to a hosted agent. The hard problem is no longer just generating the next answer. It is carrying governed Work from context to execution and retaining evidence of the result.
Astra makes that full loop part of the runtime:
| Runtime responsibility | Enterprise question | Astra system |
|---|---|---|
| Durable Work | How does work survive requests, reconnects, retries, and handoffs? | Agent Kernel: Session, Run, Turn, Work, task graphs, checkpoints, and recovery |
| Context | What should the agent know right now? | Context Pipeline: governed assembly, precedence, provenance, budgets, compression, and cache-stable structure |
| Control | What is this identity allowed to do? | Policy and provider admission: permission, side effects, routing, fallback, and result quality |
| Execution | Where should the action happen? | Server providers, User Runners deployed through CLI or Edge, MCP, and managed sandboxes |
| Evidence | What happened, why, and what should happen next? | Trace, Introspect, Explain, Reflect, and Audit |
Text version
Context Pipeline
│ assemble task, enterprise, runtime, and memory state
▼
Model decision
│
▼
Policy + provider admission
│ bind identity, capability, permission, and execution route
▼
Runner inside the owning environment
│ tools · workspace · private network · enterprise systems
▼
Trace ──► Introspect ──► Explain / Reflect
│
└──► durable Work and future context
Models and tools can change. Astra preserves the context, execution boundary, lifecycle, provider decision, and evidence model around them.
Astra uses the same backbone across CLI + Server, Server-only, and Server + Edge / User Runner deployments. In private environments, the Server coordinates while the Runner acts alongside the systems that own the tools, data, network, and credentials.
If your use case is one stateless model call, a direct LLM API is usually simpler. Astra is designed for the point where state, tools, permissions, recovery, collaboration, or operational control become part of the product.
ContextPipe: Database-Inspired Context Assembly for Long-Horizon Agents presents Astra's Context Pipeline as a five-phase system—Plan, Bind, Optimize, Execute, and Feedback—with structured data sources, deterministic cache-aware optimization, and an EXPLAIN ANALYZE trace.
Peng Xu, Zuyu Zhang, Yuze Sun, Feng Tian, Long Wang, and Chen Zhang · Accepted at ADS 2026, co-located with VLDB 2026 · arXiv · PDF · Citation
In a preliminary evaluation on the SWE-bench Pro Qutebrowser subset, ContextPipe reduced total token volume by 31%, LLM calls by 23%, and response time by 9% compared with append-only context construction, with a lower KV cache-hit ratio as the measured tradeoff.
Terminal-Bench evaluates agents on difficult, realistic terminal tasks. Across its 89 tasks, Astra ranks first with 60 verifier-passing results (67.42%).
Model: GLM-5.2 for every agent in the comparison.
| Agent | Overall | Easy | Medium | Hard |
|---|---|---|---|---|
| Astra | 60 / 89 (67.42%) | 4 / 4 (100%) | 42 / 55 (76.36%) | 14 / 30 (46.67%) |
| Pi | 54 / 89 (60.67%) | 4 / 4 (100%) | 36 / 55 (65.45%) | 14 / 30 (46.67%) |
| Hermes | 51 / 89 (57.30%) | 4 / 4 (100%) | 32 / 55 (58.18%) | 15 / 30 (50.00%) |
| DeepSeek Harness (DSH) | 48 / 89 (53.93%) | 4 / 4 (100%) | 31 / 55 (56.36%) | 13 / 30 (43.33%) |
Astra's lead is clearest on the 55 medium-difficulty tasks: it passes six more than Pi, ten more than Hermes, and eleven more than DSH. On hard tasks, Astra ties Pi, finishes one task behind Hermes, and one ahead of DSH.
The path below builds Astra from source and starts the Server-only profile. For Docker and production paths, use the getting-started guide.
- Git and Make
- Docker with Docker Compose
- Rust via
rustup(the repository pins Rust 1.97) - Node.js 24 (pinned in
.nvmrc) and OpenSSL command-line tools - An embedding API and at least one supported LLM endpoint
git clone https://github.com/matrixorigin/astra.git
cd astra
cp .models.yaml.example .models.yaml
make dev-initSet MEMORIA_EMBEDDING_API_KEY and MEMORIA_EMBEDDING_BASE_URL in .env,
then configure at least one provider in .models.yaml. Never commit either
local file.
make build
make dev-start-server-only
export PATH="$PWD/target/release:$PATH"
astra health| Service | Default URL |
|---|---|
| Web dashboard | http://localhost:3536 |
| HTTP API | http://localhost:17001 |
| Health check | http://localhost:17001/health |
The first admin registration bootstraps a fresh installation and stores its credentials in the local CLI profile.
astra admin register
astra admin model load .models.yaml --update-existing
astra admin model check YOUR_MODEL_NAME
astraYou can now use the TUI or send a one-shot request:
astra chat -m "Map this repository and explain its architecture"Server-only mode deliberately has no implicit access to your machine. Connect a User Runner when a Web session needs local file, shell, Git, build/test, or private-network capacity:
ASTRA_EDGE_WORKSPACE_DIR=/path/to/workspace make dev-edge-startUse make dev-start-server-edge on later starts to bring up the Server, Web
dashboard, and local User Runner together.
astra # interactive TUI
astra chat -m "Investigate the failing tests"
astra chat -m "Continue" --session-id SESSION_ID
astra -p "Summarize this text" # print mode; no tools
astra chat -m "Review the diff" --quiet
astra chat -m "Summarize the changes" --json
astra chat -m "Design the migration" --permission-mode plan
astra chat -m "Run tests and fix failures" --permission-mode autoInside the TUI, type / to discover commands. Common entries include
/model, /session, /skill, /memory, /plan, /checkpoint, /review,
/team, /explain, and /help.
astra work start --done-when "tests pass" "Diagnose and fix the regression"
astra work show WORK_ID
astra work continue WORK_ID "Also verify the migration path"
astra session list
astra audit list
astra self snapshotastra skill list
astra mcp list
astra team list
astra memory search "deployment preferences"astra serve http --host 127.0.0.1 --port 17001
astra serve stdioHTTP mode exposes the Axum API, SSE, and WebSocket transports. Stdio mode is a long-lived newline-delimited JSON-RPC app-server for parent processes. See the CLI reference, HTTP API, and TypeScript SDK for complete integration contracts.
Astra has one durable agent backbone and multiple bounded capacity providers. Interfaces do not own separate agent loops; each environment contributes the capabilities it can safely execute.
Text version
Experience
Web dashboard · CLI/TUI · TypeScript SDK · API clients
│
▼
Durable control backbone
Server · Session/Run/Work · identity · orchestration · checkpoints
│
▼
Context Pipeline ──► model decision ──► Policy + provider decision
▲ │
│ ▼
│ Execution capacity
│ ┌─────────────┼───────────────┐
│ ▼ ▼ ▼
│ Server provider User Runner MCP / sandbox
│ CLI or Edge scoped runtime
│ │
│ ▼
│ Private enterprise IT
│ workspace · network · tools · data
│ │
└──── Trace · Introspect · Explain · Reflect · Audit
Durable facts
MatrixOne · Memoria · transcript · artifacts · checkpoints · trace · audit
One lifecycle connects four system planes: Intelligence assembles context, Control owns durable Work and policy, Execution supplies bounded capacity, and Evidence preserves facts and turns them into operational understanding.
| Runtime profile | Execution shape | Best suited for |
|---|---|---|
| CLI + Server | Server backbone, CLI/TUI interaction, and CLI-local workspace capacity | Developers, operators, automation, and terminal-first work |
| Server-only | Web, SDK, or enterprise apps use durable Server state and governed Server-side providers | Central services, knowledge work, and controlled business workflows |
| Server + Edge / User Runner | Server dispatches admitted work to a Runner inside a user or enterprise environment | Hybrid cloud/private execution, source code, internal systems, and user-owned environments |
These profiles change available capacity, not agent identity. CLI is an interaction surface with optional local execution; Server is the durable orchestration and control backbone; Edge places Runner capacity close to private IT. All three share one context, policy, lifecycle, and evidence model.
The central invariant is:
enterprise agent = durable Work + governed context + authorized execution + verifiable evidence
The backbone owns lifecycle and runtime truth. The Context Pipeline determines what enters the model boundary. Policy and provider admission determine which capabilities are visible and where they may execute. Runners and other capacity providers declare what they can do, where they execute, whether they are available, and which trust boundary applies. Their results return to the same Work, trace, audit, and context lifecycle.
| Provider | Typical capacity | Trust boundary |
|---|---|---|
| Server | Shared state, memory, configured network access, reports, control-plane tools | Hosted runtime |
| User Runner (CLI-local or Edge) | Files, shell, Git, builds, tests, local network, local MCP, and access to existing private IT through locally available tools | User or enterprise identity, workspace, network, and runtime |
| MCP | Business APIs, databases, knowledge bases, ticketing, approvals | MCP server and request binding |
| Sandbox / managed runtime | Isolated scripts and provisioned workspace execution | Explicit runtime binding |
When a provider disconnects, its capacity can become unavailable without erasing the session, plan, memory, or server-side Work. Read the architecture overview and agent-backbone contract for the complete design.
Claude Code, Codex, Pi, and DeepSeek Harness are strong systems for interactive coding or composing an agent harness. Astra expands the boundary from one coding loop to an enterprise-owned runtime across users, applications, private environments, and trust boundaries.
Models decide. Runners act. Astra governs and traces the entire loop.
| System | Primary design center | Astra's distinction |
|---|---|---|
| Claude Code | Developer-facing coding agent across terminal, IDE, tools, and enterprise model endpoints | Astra makes the durable enterprise runtime—not one coding surface—the system of record |
| Codex | Coding agent across local, cloud, IDE, automation, and integration surfaces | Astra is model-provider independent and centers self-hosted backbone state, User Runners, and governed providers |
| Pi | Minimal terminal coding harness extended through TypeScript packages, skills, prompts, and themes | Astra centers a distributed Server/Runner architecture, durable Work, enterprise identity, and operations |
| DeepSeek Harness | Plugin-first harness with composable capabilities, runtime modes, and a traceable session log | Astra centers canonical lifecycle state, cross-user control, provider decisions, and user-bound execution |
| Astra | Enterprise context-to-execution runtime | One durable backbone connecting governed context to execution across Web, CLI, Server, Edge, MCP, sandboxes, and User Runners |
The distinction is architectural:
- The enterprise owns durable Work — identity, tasks, model routes, policy, trace, and audit live in an operable system of record.
- Context is a pipeline — structured inputs are assembled, budgeted, compressed, traced, and recovered as runtime state.
- Execution follows authority — Server, User Runner, MCP, and sandbox capacity is explicitly bound, admitted, routed, and governed.
- Every surface shares semantics — Web, TUI, SDK, and Runner-backed sessions use the same lifecycle, failure, and evidence model.
Coding is an important Astra workload, but it is not the product boundary. Astra is designed to be self-hosted, embedded, extended, and exposed through enterprise products.
The kernel turns an interaction into durable, controllable Work. The assistant's last message is not the authority for whether a task exists, which attempt owns it, or whether it has been verified.
Session
├── Run
│ ├── Turn
│ │ ├── Model boundary
│ │ └── Tool lifecycle
│ ├── Checkpoint
│ └── Events / artifacts
└── Work
└── Versioned task graph
└── Attempt → verification → delivery
- Session preserves the continuous user/agent relationship across surfaces.
- Run is a controllable execution attempt with ownership and terminal state.
- Work gives a long-lived goal stable identity beyond an individual chat.
- Task graph records decomposition, dependencies, attempts, verification, and delivery.
- Checkpoints and events make pause, resume, reconnect, and recovery reconstructable from durable facts.
Text version
queued → running → completed
├── waiting ──→ running
├── paused ──→ running
├── blocked ──→ running
├── cancelling → cancelled
└── failed
The Context Pipeline is a core Astra kernel contribution described in ContextPipe, Astra's systems paper accepted at ADS 2026, co-located with VLDB 2026. It is the intelligence plane between durable enterprise state and each model decision. Context is treated as a governed, recoverable data pipeline—not one indefinitely growing prompt string and not a one-time retrieval step.
Text version
System contract ─────────────┐
Session · Run · Work ────────┤
Memory · enterprise facts ───┤
Artifacts · tool results ────┤──► assemble ─► select/budget/compress ─► model
Runner · provider · policy ──┤ │
Trace · reflection ──────────┘ ▼
decision · usage · checkpoint
│
└──► future context
At every model boundary, the pipeline turns the current Work, memory, artifacts, runtime availability, policy state, and prior execution facts into a bounded context for the next decision. Runner results and Trace then become inputs to future turns, closing the loop between knowing and acting.
The pipeline provides stable prompt-cache-friendly contracts, typed dynamic state, explicit precedence and provenance, budget-aware selection, semantic compression, and reconstruction from checkpoints and durable facts.
Tool visibility and tool execution use the same lifecycle:
Projection → Admission → Execution → Result
Each decision considers identity, mode, side-effect class, permission scope, workspace authority, provider binding and health, runtime location, fallback policy, and result quality. The outcome drives the model-visible tool surface, execution route, user diagnostics, trace, and audit. Ready, policy-blocked, unbound, offline, unsupported, and fallback outcomes are explicit runtime facts. A narrow capability failure blocks that action rather than erasing the session or pretending the capability never existed. See the capability contract for the full state model.
A Runner is Astra's deployable execution boundary: the place where an
admitted action becomes real work. A User Runner binds that execution to a
specific user and workspace. Today this role is provided by astra-edge and
the CLI-local runtime.
The Server coordinates. The Runner acts.
| Term | Meaning |
|---|---|
| Runner | The execution contract that supplies bounded capabilities to the shared agent backbone |
| User Runner | A Runner bound to a user's identity, workspace, tools, network, and permission boundary |
| Edge | A deployment topology that places Runner capacity near the private systems where work must happen |
Runner and Edge are therefore not synonyms: Runner describes the execution boundary; Edge describes where that boundary is deployed. A User Runner describes who owns and authorizes it.
Text version
User / app
│ submit durable Work
▼
Astra Server ── durable Work · identity · context · policy · provider decision
│ admitted tool call
▼
User Runner ── inside the user or enterprise trust boundary
│
▼
Private enterprise IT
file · shell · Git · builds · private network · local MCP
│
└──── typed result + execution identity + evidence ────► backbone
This is the last-mile integration layer between an agent and the systems where enterprise work already lives. Instead of exposing every internal system to a hosted agent or granting the Server ambient machine access, an enterprise can place Runner capacity alongside its existing workspace, network, tools, and identity controls.
Runner placement controls execution locality; it does not by itself guarantee data residency. Model endpoints, context disclosure, and tool-result handling remain explicit deployment and policy choices.
The Runner contributes bounded execution capacity, not a second agent brain:
- registration and dispatch stay bound to user, Runner, and workspace identity;
- explicit capabilities replace implicit Server access to the user's machine;
- permissions remain enforced where execution occurs;
- heartbeats, journals, reconnects, and reconciliation make results observable, recoverable, and part of the same transcript, trace, audit, and checkpoints.
The observation plane is part of the agent contract, not an after-the-fact log viewer:
Text version
Runtime facts ──► Trace ──► Introspect ──► Explain
│ └──────► Reflect
│
Policy decisions ───┴─────────────► Audit
| Component | Question it answers | Authority |
|---|---|---|
| Trace | What happened, in which causal order, through which model, tool, and provider? | Records measured execution facts |
| Introspect | What is the current run, context, task, budget, capability, and blocked state? | Reads and structures current facts |
| Explain | Why is the run working, waiting, degraded, blocked, or failed, and what can the user do? | Presents a user-facing projection of facts |
| Reflect | What may be wrong, and should strategy change or human help be requested? | Proposes advice; cannot grant permission or complete tasks |
| Audit | Which identity, permission, provider, fallback, and side-effect facts remain accountable? | Preserves durable accountability records |
Reflection cannot rewrite runtime truth, Explain does not expose private chain-of-thought, and debug output is not automatically an audit record.
Astra supports local source development, all-in-one Compose, Kubernetes, and Server + Edge / User Runner topologies. Start with the deployment overview.
Runtime and model configuration are intentionally separate:
.env.examplecovers database, authentication, Memoria, runtime limits, logging, and optional provider bindings..models.yaml.exampledefines model endpoints, credentials, capabilities, pricing, and fallback chains.config/server.toml.exampleis the file-based server baseline;ASTRA_*environment variables take precedence.
Server observability uses structured logs and optional OTLP export, while CLI diagnostics stay separate from machine-readable output. See the configuration reference, production guide, and troubleshooting guide.
The README is the product overview and shortest runnable path. Detailed documentation is organized by reader goal:
| I want to... | Start here | Continue with |
|---|---|---|
| Try and use Astra | Getting started | CLI commands and TUI slash commands |
| Build an application | TypeScript SDK | HTTP API and examples |
| Deploy and operate | Deployment overview | Configuration and troubleshooting |
| Get help or report a problem | Support | Questions, bug reports, documentation issues, and feature requests |
| Develop and contribute | Contributing guide | Developer setup, workflow, testing, and Make targets |
| Understand the kernel | Architecture | Design index, lifecycle, and capabilities |
The full documentation index separates current user and operator guidance from normative design contracts.
make dev-status # inspect local services
make test-offline # unit, contract, SDK, Web, and runtime-profile tests
make test-contract # focused HTTP/admin/config contracts
make check # clippy, formatting, Rust types, and Web checks
make test # complete suite; live dependencies are required
make dev-stop # stop the local development environmentUse the smallest relevant package while iterating, then run the repository gates before opening a pull request. The testing guide explains the offline, contract, live MatrixOne, and system-matrix lanes.
Repository layout
crates/
astra-cli/ Interactive TUI, scripting CLI, and local tools
runtime/ Axum server, API routes, and runtime composition
astra-turn-core/ Agent-turn orchestration and lifecycle semantics
services/ Durable sessions, runs, auth, audit, and admin services
astra-edge/ User Runner provider and cloud connection
astra-tools/ Tool contracts and shared execution types
astra-mcp/ MCP integration
astra-skills/ Skill discovery and execution support
astra-sandbox/ Managed execution boundaries
packages/sdk/ TypeScript and React SDK
web/ Next.js dashboard
deployment/ Compose, Kubernetes, and cloud deployment examples
docs/ Design contracts, guides, reference, and testing docs
Issues and pull requests are welcome. Before submitting a change:
- Read the owning contract in
docs/design/. - Add or update tests at the narrowest responsible layer.
- Run
make checkand the relevant offline or integration lane. - Describe user-visible behavior, failure semantics, and provider-boundary changes in the pull request.
For substantial behavior changes, open an issue first so the runtime contract and implementation can evolve together.
Astra is licensed under the Apache License, Version 2.0.
Astra connects enterprise context to governed execution across CLI, Server, and Edge—with traceability built in.