Astra

An agent runtime with EXPLAIN ANALYZE for context

Inspect context and state. Adjust and recover with evidence. Run in your environment.

Why Astra · Research · Quick start · Architecture · Runner · Comparison · Docs

---

Astra is a self-hosted runtime for long-running agent Work. Every model request is assembled by a budgeted pipeline you can EXPLAIN, every attempt leaves evidence you can inspect, diff, and roll back, and execution runs through a Runner inside your own environment.

What did the model receive?	What changed, and what next?	Where does it run?
EXPLAIN ANALYZE shows context-source estimates, request-budget estimates, provider usage, execution timing, and which boundaries were not measured. Self exposes goals, budgets, and tool health. ContextPipe cut tokens 31% against append-only context.	Every attempt, config change, and checkpoint is versioned. Rewind a session, diff two runs, replay against the record, and continue durable Work with a new constraint.	A User Runner executes admitted tool calls in your repositories and networks. The Server coordinates; it never gets ambient access to your machine.
Understand what happened.	Know what changed and what still needs verification.	Keep code and credentials where they are.

astra chat --explain verbose -m "Run the shell command: ls *.sh | wc -l and answer with just the number."

Explain Analyze · recorded · 10 stages · 10/10 timed spans · 1 clock domains
  Observed overlap · at least 2 overlapping recorded spans
  Not timed separately · some approval waits · tool I/O wait breakdown · child-run timing · time to first token · provider retry backoff · user input waits
  Provider tokens · in 83,200 · cache read 0 · cache write 0 · out 54
User turn · 2.4s · Completed · clock A +0ms
├─ Understand requested outcome · 25ms · Resolved · round 1 · clock A +0ms
├─ Prepare model request · 65ms · Succeeded · round 1 · attempt 1 · clock A +25ms
│  └─ Assemble context sources · 55ms · Succeeded · round 1 · clock A +28ms
├─ Generate model response · 1.1s · Succeeded · round 1 · clock A +95ms
│  └─ Model request · 1.0s · Succeeded · round 1 · attempt 1 · clock A +100ms
├─ Execute selected tools · 700ms · Succeeded · round 1 · attempt 1 · clock A +1.2s
│  ├─ Run read_file · 600ms · Succeeded · round 1 · clock A +1.25s
│  └─ Run search_repository · 450ms · Succeeded · round 1 · clock A +1.25s
└─ Deliver final answer · 100ms · Completed · clock A +2.29s

_{Illustrative Explain Analyze tree. Runtime facts carry provider token lanes and measured intervals; context costs remain estimates, and known unmeasured boundaries stay visible.}

Astra ships as one binary (CLI, TUI, and Server), plus a Web dashboard and a TypeScript SDK sharing one agent backbone. Bring any model endpoint.

_{Illustrative recorded-event replay through the real Web component. Tree is the default; Timeline and Graph are optional. Missing failure explanations and unmeasured I/O time are explicitly identified.}

Pick the layer you need

All three can run models and tools. The difference is what each system makes authoritative.

	Codex	DeepSeek Harness	Astra
You are choosing	A ready-to-use agent and embeddable harness	A composable agent harness	A shared, self-hosted agent runtime
System of record	The Codex task and workspace	An append-only session event stream assembled from plugins	Durable Work, identity, policy, provider decisions, trace, and audit across users and applications
Execution boundary	The local or cloud environment selected for the task	Configured tools, sandboxes, storage, and runtime plugins	The Server admits the action; a user-bound Runner executes inside the private environment
Best fit	Use an agent directly to complete work	Build or customize a coding agent and its runtime	Operate governed infrastructure behind many agents, products, and trust boundaries

Use Astra when an agent becomes shared infrastructure across users, applications, private networks, and approval boundaries. If all you need is a prompt-and-tools loop on one machine, a lighter agent framework or coding agent is usually simpler.

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.

Why Astra

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

From context to execution

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.

Research and benchmarks

ContextPipe

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 2.1

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.

Quick start

The fastest path is the hosted Astra Server: the Server and Memoria are already running; you install the CLI, log in, and add one model API key. Nothing else to deploy.

1. Install the CLI

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/matrixorigin/Astra/main/scripts/install-astra.sh | sh

The script verifies the checksum and installs astra (and astra-edge) into /usr/local/bin, or ~/.local/bin when that is not writable; pass --dir PATH to choose. Linux (amd64, arm64) and macOS (Apple Silicon, Intel) are supported. Linux binaries are static and need nothing else. On macOS the binary links against Homebrew's OpenSSL 3, so run brew install openssl@3 first.

2. Point the CLI at the hosted Server and log in

astra config set api_url https://astra.thememoria.ai
astra login

astra login prints a https://thememoria.ai/connect/astra?... link and waits; open it in a browser, approve, and the CLI stores the credentials in ~/.astra/credentials.json. On a machine without a browser, use astra login --manual and paste a connection key from thememoria.ai. astra whoami confirms the account.

3. Add your model

Astra is BYOK: the key is stored on the Server for your account and never in the local config. The wizard asks for provider, model id, and key (hidden input) and marks the model as your default:

astra model add

Or non-interactively, for example with DeepSeek:

printf '%s' "$DEEPSEEK_API_KEY" | astra model add deepseek --provider deepseek --model deepseek-v4-flash --context-window 128000 --api-key-stdin --default

Providers: openai, anthropic, deepseek, and openai-compatible with --base-url for GLM, Qwen, Kimi, or a gateway. --model is the provider's exact model id; the first argument is the alias you use later. Then verify the credential and endpoint from the Server side:

astra model probe deepseek

4. Run

astra                                   # interactive TUI; type / for commands
astra chat -m "Map this repository and explain its architecture"
astra chat -y --explain verbose -m "Count the .sh files here with a shell command"

File, shell, and Git tools run on this machine inside the current directory; the Server only sees tool results. One-shot chat cannot ask for approval, so pass -y (or --permission-mode auto) when the task needs tools; the TUI prompts instead. --explain verbose prints the runtime-recorded Explain Analyze execution tree for the turn, with known unmeasured boundaries shown.

If a command returns 401, the access token has expired: run astra refresh. astra doctor checks the install, Server, and login in one go. Sessions and journals live under ~/.astra.

To run the Server yourself instead, use one of the two self-hosted paths below. Both end at the same CLI commands as the hosted path.

Self-host with Docker

No Rust or Node toolchain. These steps run all the way to a real agent response, not just a healthy port.

1. Install the client binaries

One checksum-verified archive installs both the astra CLI and the astra-edge User Runner — Linux and macOS, amd64 and arm64:

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/matrixorigin/Astra/main/scripts/install-astra.sh | sh -s -- --dir "$HOME/.local/bin"
export PATH="$HOME/.local/bin:$PATH"

2. Run the guided setup

Use the same version for the client and Server deployment, then follow one guided flow from embedding configuration through the first administrator and model. The installer prints these version-matched next steps as well:

ASTRA_VERSION="$(astra --version | awk '{print $2}')"
git clone --branch "v${ASTRA_VERSION}" --depth 1 https://github.com/matrixorigin/Astra.git "Astra-${ASTRA_VERSION}"
cd "Astra-${ASTRA_VERSION}"
make stack-setup

The guided setup first identifies the intended local installation and prints a status snapshot on every run. If an older or differently configured stack exists, you explicitly choose whether to update it, create a separate installation with its own data and ports, or leave it untouched. It then validates the embedding endpoint, credentials, model, and vector dimension before starting containers. Healthy services are reused; partial services get explicit repair, stop, and inspect choices. API keys are hidden while typing and the local .env is owner-only. Choose mock embeddings for deterministic evaluation; use a real OpenAI-compatible endpoint for production retrieval. Mock embeddings do not provide an LLM: the model step still needs a supported hosted or local model endpoint. Administrator/model setup is optional: choose to finish the infrastructure and resume it later. The wizard distinguishes Stack ready from Chat ready, never deletes persistent volumes, and saves the selected API URL for later CLI runs. The released clients and full guided path support Linux, macOS, and Windows through WSL. Native Windows and Git Bash are not release targets yet.

For a non-interactive local evaluation, use deterministic mock embeddings:

MEMORIA_EMBEDDING_PROVIDER=mock make stack-start

For semantic memory, set MEMORIA_EMBEDDING_BASE_URL and, when required, MEMORIA_EMBEDDING_API_KEY, then run make stack-start. The command generates local secrets, starts Compose, waits for health, and verifies an exact memory round trip. For lower-level automation, run make stack-env, make stack-up, and make stack-verify explicitly.

Service	Default URL
HTTP API	http://localhost:17001
Health check	http://localhost:17001/health

3. Confirm the CLI and service

The versioned stack ships the matching astra-server; the prebuilt astra binary installed in step 1 drives it:

astra health
astra

astra health returns a non-zero status when the API reports an unhealthy or degraded dependency. Guided setup saves its API address in CLI settings, so a remapped port also works for later astra TUI sessions. For a manually managed stack, run astra config set api_url http://127.0.0.1:<port>. Pass -v <version> to the installer to select an older or prerelease client; always use its matching Git tag for the deployment checkout. MatrixOne and Memoria are pinned to the compatibility set exercised by that Astra release instead of floating on latest.

For scripted or advanced environments, replace the guided account/model phase with the following two operations.

Bootstrap the admin account

astra admin register --username admin --password '<password>'

On a fresh data volume this creates the initial administrator and stores the returned credentials in the local CLI profile. After an administrator exists, the command must be run while logged in as an existing administrator.

Register a model

astra admin model add MODEL_NAME openai \
  --api-key "$LLM_API_KEY" --context-window 128000 \
  --base-url https://your-endpoint/v1
astra admin model check MODEL_NAME

model check probes the endpoint and reports is_active and connectivity. A model reaches is_active: true only when the probe succeeds, so this is the step that tells you routing will work. For more than one model, write a .models.yaml and run astra admin model load .models.yaml --update-existing.

4. Get the first agent response

astra chat -m "Explain what you can and cannot do in this deployment"
astra session list

You are through the loop when the request returns a model response and session list shows the durable session it created.

This stack is Server-only by design. Server-side agent turns, memory, planning, MCP, and introspection are available, while file, shell, Git, build/test, and private-network tools stay unavailable until a Runner connects — which is what the answer above should tell you.

5. Connect a User Runner when local execution is needed

After the CLI has stored your account credentials, expose one deliberate local workspace to the Server:

astra-edge --workspace-dir /path/to/workspace

The Runner inherits the selected Astra CLI profile and reconnects on transient disconnects. Stop it to remove that execution capacity; the Server remains available without ambient access to the machine. Operate the stack with make stack-status, make stack-logs SERVICE=api, and make stack-down. The all-in-one guide covers the server+edge profile; the Docker quick start covers ports and troubleshooting.

Self-host from source

This path builds the astra binary and starts the Server-only profile with the Web dashboard.

1. Initialize

git clone https://github.com/matrixorigin/Astra.git
cd Astra

cp .models.yaml.example .models.yaml
make dev-init

Configure a real embedding endpoint in .env for semantic memory, adding an API key only when that endpoint requires one, or set MEMORIA_EMBEDDING_PROVIDER=mock for local evaluation. Then configure at least one model provider in .models.yaml. Never commit either local file.

2. Build and start Server-only

make build-cli-debug
make dev-start

export PATH="$PWD/target/debug:$PATH"
astra health

Service	Default URL
Web dashboard	http://localhost:3536
HTTP API	http://localhost:17001
Health check	http://localhost:17001/health

3. Bootstrap an account and model

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

astra

You can now use the TUI or send a one-shot request:

astra chat -m "Map this repository and explain its architecture"

4. Add a User Runner when local execution is needed

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-start

Use make dev-start-server-edge on later starts to bring up the Server, Web dashboard, and local User Runner together.

Use Astra

Interactive, one-shot, and automation

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 auto

Inside the TUI, type / to discover commands. Common entries include /model, /session, /skill, /memory, /plan, /checkpoint, /review, /team, /explain, and /help.

Durable Work and inspection

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 snapshot

Skills, MCP, teams, and memory

astra skill list
astra mcp list
astra team list
astra memory search "deployment preferences"

Embed Astra

astra serve http --host 127.0.0.1 --port 17001
astra serve stdio

HTTP 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.

Architecture

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.

One runtime from CLI to Server to Edge

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.

How Astra differs from coding agents

Claude Code, Codex, Pi, and DeepSeek Harness are strong systems for completing work or composing an agent harness. Astra expands the system of record from an agent task or session 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	Agent product 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	Local-first, plugin-composable coding agent and runtime with 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.

Core runtime systems

Durable Agent Kernel

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

Context Pipeline

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.

Policy and governed execution

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.

Runner and private enterprise IT

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.

Trace, Introspect, Explain, Reflect, and Audit

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.

Deploy and operate

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.example covers database, authentication, Memoria, runtime limits, logging, and optional provider bindings.
• .models.yaml.example defines model endpoints, credentials, capabilities, pricing, and fallback chains.
• config/server.toml.example is 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.

Documentation

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 configuration
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.

Development and contributing

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 environment

Use 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:

1. Read the owning contract in docs/design/.
2. Add or update tests at the narrowest responsible layer.
3. Run make check and the relevant offline or integration lane.
4. 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.

Citation

If Astra or the Context Pipeline is useful in your research, please cite the ContextPipe paper:

@inproceedings{xu2026contextpipe,
  title         = {ContextPipe: Database-Inspired Context Assembly for Long-Horizon Agents},
  author        = {Xu, Peng and Zhang, Zuyu and Sun, Yuze and Tian, Feng and Wang, Long and Zhang, Chen},
  booktitle     = {Applied Data Science Track (ADS 2026), co-located with VLDB 2026},
  year          = {2026},
  eprint        = {2609.00749},
  archivePrefix = {arXiv},
  url           = {https://arxiv.org/abs/2609.00749}
}

CITATION.cff also lets GitHub generate APA and BibTeX entries for the software itself through Cite this repository.

License

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.