How matrixorigin/astra works
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: run/engine.rs Astra Server · session_runtime.rs CLI / TUI · delegation/engine.rs Delegation · native_auth.rs Native Authentication
Components 28
User Interfaces
- CLI / TUI
crates/astra-cli/src/cli/session/session_runtime.rs - Web Dashboard
web/app/layout.tsx - TypeScript SDK
packages/sdk/src/client.ts - Native Authentication
crates/astra-cli/src/cli/native_auth.rs - CLI Configuration
crates/astra-cli/src/cli/cli_config/cli_utils.rs - Cloud Sync
crates/astra-cli/src/cli/cloud_sync.rs - Terminal Theme
crates/astra-cli/src/cli/theme.rs
Agent Runtime
- Astra Server
crates/runtime/src/server/run/engine.rs - Context Pipeline
crates/astra-turn-core/src/context/pipeline.rs - Context Adapter
crates/runtime/src/turn/context_pipeline_adapter.rs - Agent Loop
crates/runtime/src/turn/agentic_loop/host.rs - Delegation
crates/runtime/src/server/delegation/engine.rs - Agent Spawner
crates/runtime/src/orchestration/spawner.rs
Governed Execution
- Tool Engine
crates/astra-tools/src/tool_engine.rs - Permission Decisions
crates/astra-turn-core/src/permission/engine.rs - User Runner
crates/astra-edge/src/main.rs - CLI Permissions
crates/astra-cli/src/cli/permission_manager.rs - Edge Token Manager
crates/astra-edge/src/token_manager.rs
Work and Evidence
- Durable Run State
crates/runtime/src/data_layer/storage.rs - Work Plans
crates/astra-plan/src/repository.rs - Execution Trace
crates/astra-pipeline/src/step_recorder.rs - Explain Analyze
crates/astra-cli/src/explain_analyze_report.rs - Pipeline Analysis
crates/astra-test-harness/src/pipeline_analysis.rs - Session Capture
crates/astra-test-harness/src/session_capture.rs - Evaluation Criteria
crates/astra-test-harness/src/criteria.rs
Services and Clients
- MCP Integration
crates/astra-mcp/src/tools.rs - Agent Messaging
crates/astra-messaging/src/router.rs
Other components
- User
Connections 30
- 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
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
crates/runtime/src/server/run/engine.rs - Astra Server → Delegation: coordinates sub-runs
crates/runtime/src/server/delegation/engine.rs - Delegation → Agent Spawner: spawns agents
crates/runtime/src/server/delegation/engine.rs - Delegation → Astra Server: executes sub-runs
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
crates/astra-test-harness/src/pipeline_analysis.rs - Evaluation Criteria → Pipeline Analysis: evaluates results
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
crates/astra-cli/src/cli/session/session_runtime.rs - Native Authentication → CLI Configuration: uses credentials
crates/astra-cli/src/cli/native_auth.rs - Native Authentication → Cloud Sync: triggers sync
crates/astra-cli/src/cli/native_auth.rs - CLI / TUI → CLI Permissions: checks permissions
crates/astra-cli/src/cli/session/session_runtime.rs - CLI / TUI → Terminal Theme: renders terminal
crates/astra-cli/src/cli/cli_config/cli_utils.rs - User Runner → Edge Token Manager: manages edge tokens