# matrixorigin/astra architecture

> Architecture diagram of the GitHub repository matrixorigin/astra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/matrixorigin/astra
- Repository: https://github.com/matrixorigin/astra

## Overview

Astra is a self-hosted runtime for durable agent Work, exposed through a CLI/TUI, Server, Web dashboard, and TypeScript SDK. The principal flow is a user request through context preparation and model/tool execution, with policy-controlled actions carried out by a Runner in the user’s environment; durable run state and trace make outcomes recoverable and inspectable. The README documents these product boundaries and capabilities, while the source index supports selected internal links. Many server, UI, and runner relationships are documented only at a high level, so those edges are marked unverified.

Main entry points: [`crates/runtime/src/server/run/engine.rs`](https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/server/run/engine.rs) (Astra Server), [`crates/astra-cli/src/cli/session/session_runtime.rs`](https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/session/session_runtime.rs) (CLI / TUI), [`crates/runtime/src/server/delegation/engine.rs`](https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/server/delegation/engine.rs) (Delegation), [`crates/astra-cli/src/cli/native_auth.rs`](https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/native_auth.rs) (Native Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI / TUI<br/>[session_runtime.rs]"]
  node_web["Web Dashboard<br/>[layout.tsx]"]
  node_sdk["TypeScript SDK<br/>[client.ts]"]
  node_auth["Native Authentication<br/>[native_auth.rs]"]
  node_cli_config["CLI Configuration<br/>[cli_utils.rs]"]
  node_cloud_sync["Cloud Sync<br/>[cloud_sync.rs]"]
  node_theme["Terminal Theme<br/>[theme.rs]"]
end

subgraph group_runtime["Agent Runtime"]
  node_server["Astra Server<br/>[engine.rs]"]
  node_context["Context Pipeline<br/>[pipeline.rs]"]
  node_context_adapter["Context Adapter"]
  node_agent_loop["Agent Loop<br/>[host.rs]"]
  node_delegation["Delegation<br/>[engine.rs]"]
  node_spawner["Agent Spawner<br/>[spawner.rs]"]
end

subgraph group_execution["Governed Execution"]
  node_tool_engine["Tool Engine<br/>[tool_engine.rs]"]
  node_permissions["Permission Decisions<br/>[engine.rs]"]
  node_runner["User Runner<br/>[main.rs]"]
  node_cli_permissions["CLI Permissions"]
  node_edge_tools["Edge Token Manager<br/>[token_manager.rs]"]
end

subgraph group_durability["Work and Evidence"]
  node_run_state[("Durable Run State<br/>[storage.rs]")]
  node_work_plans[("Work Plans<br/>[repository.rs]")]
  node_trace[("Execution Trace<br/>[step_recorder.rs]")]
  node_explain["Explain Analyze"]
  node_analysis["Pipeline Analysis"]
  node_capture["Session Capture<br/>[session_capture.rs]"]
  node_criteria["Evaluation Criteria<br/>[criteria.rs]"]
end

subgraph group_integration["Services and Clients"]
  node_mcp["MCP Integration<br/>[tools.rs]"]
  node_messaging["Agent Messaging<br/>[router.rs]"]
end

node_user(("User"))

node_user -.->|"submits Work"| node_cli
node_user -.->|"uses dashboard"| node_web
node_user -.->|"integrates client"| node_sdk
node_cli -.->|"requests runtime"| node_server
node_web -.->|"uses runtime"| node_server
node_sdk -.->|"calls APIs"| node_server
node_server -.->|"prepares context"| node_context_adapter
node_context_adapter -.->|"supplies inputs"| node_context
node_context -.->|"builds request"| node_agent_loop
node_agent_loop -.->|"executes tools"| node_tool_engine
node_server -.->|"admits actions"| node_permissions
node_server -.->|"dispatches admitted work"| node_runner
node_runner -.->|"runs in environment"| node_tool_engine
node_server -.->|"persists runs"| node_run_state
node_server -.->|"coordinates sub-runs"| node_delegation
node_delegation -.->|"spawns agents"| node_spawner
node_delegation -.->|"executes sub-runs"| node_server
node_server -.->|"manages durable Work"| node_work_plans
node_server -.->|"records attempts"| node_trace
node_trace -.->|"informs analysis"| node_explain
node_capture -->|"feeds diagnostics"| node_analysis
node_criteria -.->|"evaluates results"| node_analysis
node_agent_loop -.->|"uses tool integration"| node_mcp
node_delegation -.->|"coordinates agents"| node_messaging
node_cli -->|"authenticates"| node_auth
node_auth -->|"uses credentials"| node_cli_config
node_auth -->|"triggers sync"| node_cloud_sync
node_cli -.->|"checks permissions"| node_cli_permissions
node_cli -->|"renders terminal"| node_theme
node_runner -.->|"manages edge tokens"| node_edge_tools

click node_cli "https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/session/session_runtime.rs"
click node_web "https://github.com/matrixorigin/astra/blob/main/web/app/layout.tsx"
click node_sdk "https://github.com/matrixorigin/astra/blob/main/packages/sdk/src/client.ts"
click node_server "https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/server/run/engine.rs"
click node_context "https://github.com/matrixorigin/astra/blob/main/crates/astra-turn-core/src/context/pipeline.rs"
click node_context_adapter "https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/turn/context_pipeline_adapter.rs"
click node_agent_loop "https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/turn/agentic_loop/host.rs"
click node_tool_engine "https://github.com/matrixorigin/astra/blob/main/crates/astra-tools/src/tool_engine.rs"
click node_permissions "https://github.com/matrixorigin/astra/blob/main/crates/astra-turn-core/src/permission/engine.rs"
click node_runner "https://github.com/matrixorigin/astra/blob/main/crates/astra-edge/src/main.rs"
click node_delegation "https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/server/delegation/engine.rs"
click node_spawner "https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/orchestration/spawner.rs"
click node_run_state "https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/data_layer/storage.rs"
click node_work_plans "https://github.com/matrixorigin/astra/blob/main/crates/astra-plan/src/repository.rs"
click node_trace "https://github.com/matrixorigin/astra/blob/main/crates/astra-pipeline/src/step_recorder.rs"
click node_explain "https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/explain_analyze_report.rs"
click node_analysis "https://github.com/matrixorigin/astra/blob/main/crates/astra-test-harness/src/pipeline_analysis.rs"
click node_capture "https://github.com/matrixorigin/astra/blob/main/crates/astra-test-harness/src/session_capture.rs"
click node_criteria "https://github.com/matrixorigin/astra/blob/main/crates/astra-test-harness/src/criteria.rs"
click node_mcp "https://github.com/matrixorigin/astra/blob/main/crates/astra-mcp/src/tools.rs"
click node_messaging "https://github.com/matrixorigin/astra/blob/main/crates/astra-messaging/src/router.rs"
click node_auth "https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/native_auth.rs"
click node_cli_config "https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/cli_config/cli_utils.rs"
click node_cloud_sync "https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/cloud_sync.rs"
click node_cli_permissions "https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/permission_manager.rs"
click node_theme "https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/theme.rs"
click node_edge_tools "https://github.com/matrixorigin/astra/blob/main/crates/astra-edge/src/token_manager.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_web,node_sdk,node_auth,node_cli_config,node_cloud_sync,node_theme,node_user toneBlue
class node_server,node_context,node_context_adapter,node_agent_loop,node_delegation,node_spawner toneAmber
class node_tool_engine,node_permissions,node_runner,node_cli_permissions,node_edge_tools toneMint
class node_run_state,node_work_plans,node_trace,node_explain,node_analysis,node_capture,node_criteria toneRose
class node_mcp,node_messaging toneIndigo
```

## Components

### User Interfaces

- [CLI / TUI](https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/session/session_runtime.rs): `crates/astra-cli/src/cli/session/session_runtime.rs`
- [Web Dashboard](https://github.com/matrixorigin/astra/blob/main/web/app/layout.tsx): `web/app/layout.tsx`
- [TypeScript SDK](https://github.com/matrixorigin/astra/blob/main/packages/sdk/src/client.ts): `packages/sdk/src/client.ts`
- [Native Authentication](https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/native_auth.rs): `crates/astra-cli/src/cli/native_auth.rs`
- [CLI Configuration](https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/cli_config/cli_utils.rs): `crates/astra-cli/src/cli/cli_config/cli_utils.rs`
- [Cloud Sync](https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/cloud_sync.rs): `crates/astra-cli/src/cli/cloud_sync.rs`
- [Terminal Theme](https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/theme.rs): `crates/astra-cli/src/cli/theme.rs`

### Agent Runtime

- [Astra Server](https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/server/run/engine.rs): `crates/runtime/src/server/run/engine.rs`
- [Context Pipeline](https://github.com/matrixorigin/astra/blob/main/crates/astra-turn-core/src/context/pipeline.rs): `crates/astra-turn-core/src/context/pipeline.rs`
- [Context Adapter](https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/turn/context_pipeline_adapter.rs): `crates/runtime/src/turn/context_pipeline_adapter.rs`
- [Agent Loop](https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/turn/agentic_loop/host.rs): `crates/runtime/src/turn/agentic_loop/host.rs`
- [Delegation](https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/server/delegation/engine.rs): `crates/runtime/src/server/delegation/engine.rs`
- [Agent Spawner](https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/orchestration/spawner.rs): `crates/runtime/src/orchestration/spawner.rs`

### Governed Execution

- [Tool Engine](https://github.com/matrixorigin/astra/blob/main/crates/astra-tools/src/tool_engine.rs): `crates/astra-tools/src/tool_engine.rs`
- [Permission Decisions](https://github.com/matrixorigin/astra/blob/main/crates/astra-turn-core/src/permission/engine.rs): `crates/astra-turn-core/src/permission/engine.rs`
- [User Runner](https://github.com/matrixorigin/astra/blob/main/crates/astra-edge/src/main.rs): `crates/astra-edge/src/main.rs`
- [CLI Permissions](https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/cli/permission_manager.rs): `crates/astra-cli/src/cli/permission_manager.rs`
- [Edge Token Manager](https://github.com/matrixorigin/astra/blob/main/crates/astra-edge/src/token_manager.rs): `crates/astra-edge/src/token_manager.rs`

### Work and Evidence

- [Durable Run State](https://github.com/matrixorigin/astra/blob/main/crates/runtime/src/data_layer/storage.rs): `crates/runtime/src/data_layer/storage.rs`
- [Work Plans](https://github.com/matrixorigin/astra/blob/main/crates/astra-plan/src/repository.rs): `crates/astra-plan/src/repository.rs`
- [Execution Trace](https://github.com/matrixorigin/astra/blob/main/crates/astra-pipeline/src/step_recorder.rs): `crates/astra-pipeline/src/step_recorder.rs`
- [Explain Analyze](https://github.com/matrixorigin/astra/blob/main/crates/astra-cli/src/explain_analyze_report.rs): `crates/astra-cli/src/explain_analyze_report.rs`
- [Pipeline Analysis](https://github.com/matrixorigin/astra/blob/main/crates/astra-test-harness/src/pipeline_analysis.rs): `crates/astra-test-harness/src/pipeline_analysis.rs`
- [Session Capture](https://github.com/matrixorigin/astra/blob/main/crates/astra-test-harness/src/session_capture.rs): `crates/astra-test-harness/src/session_capture.rs`
- [Evaluation Criteria](https://github.com/matrixorigin/astra/blob/main/crates/astra-test-harness/src/criteria.rs): `crates/astra-test-harness/src/criteria.rs`

### Services and Clients

- [MCP Integration](https://github.com/matrixorigin/astra/blob/main/crates/astra-mcp/src/tools.rs): `crates/astra-mcp/src/tools.rs`
- [Agent Messaging](https://github.com/matrixorigin/astra/blob/main/crates/astra-messaging/src/router.rs): `crates/astra-messaging/src/router.rs`

### Other components

- **User**

## Connections

- User → CLI / TUI: submits Work
- User → Web Dashboard: uses dashboard
- User → TypeScript SDK: integrates client
- CLI / TUI → Astra Server: requests runtime
- Web Dashboard → Astra Server: uses runtime
- TypeScript SDK → Astra Server: calls APIs
- Astra Server → Context Adapter: prepares context
- Context Adapter → Context Pipeline: supplies inputs (evidence: `crates/runtime/src/turn/context_pipeline_adapter.rs`)
- Context Pipeline → Agent Loop: builds request
- Agent Loop → Tool Engine: executes tools
- Astra Server → Permission Decisions: admits actions
- Astra Server → User Runner: dispatches admitted work
- User Runner → Tool Engine: runs in environment
- Astra Server → Durable Run State: persists runs (evidence: `crates/runtime/src/server/run/engine.rs`)
- Astra Server → Delegation: coordinates sub-runs (evidence: `crates/runtime/src/server/delegation/engine.rs`)
- Delegation → Agent Spawner: spawns agents (evidence: `crates/runtime/src/server/delegation/engine.rs`)
- Delegation → Astra Server: executes sub-runs (evidence: `crates/runtime/src/server/delegation/engine.rs`)
- Astra Server → Work Plans: manages durable Work
- Astra Server → Execution Trace: records attempts
- Execution Trace → Explain Analyze: informs analysis
- Session Capture → Pipeline Analysis: feeds diagnostics (evidence: `crates/astra-test-harness/src/pipeline_analysis.rs`)
- Evaluation Criteria → Pipeline Analysis: evaluates results (evidence: `crates/astra-test-harness/src/pipeline_analysis.rs`)
- Agent Loop → MCP Integration: uses tool integration
- Delegation → Agent Messaging: coordinates agents
- CLI / TUI → Native Authentication: authenticates (evidence: `crates/astra-cli/src/cli/session/session_runtime.rs`)
- Native Authentication → CLI Configuration: uses credentials (evidence: `crates/astra-cli/src/cli/native_auth.rs`)
- Native Authentication → Cloud Sync: triggers sync (evidence: `crates/astra-cli/src/cli/native_auth.rs`)
- CLI / TUI → CLI Permissions: checks permissions (evidence: `crates/astra-cli/src/cli/session/session_runtime.rs`)
- CLI / TUI → Terminal Theme: renders terminal (evidence: `crates/astra-cli/src/cli/cli_config/cli_utils.rs`)
- User Runner → Edge Token Manager: manages edge tokens
