How reedsha/aleth works
Aleth is a local, single-process AI execution engine with a browser UI and typed API. A user submits a task; the engine routes it through planning and agent execution, runs code in disposable containers against a shadow workspace, and presents changes for approval before merge. Retrieval, structured plan parsing, and persistent run state support that workflow; the README also documents boot checks, migrations, maintenance, and a loopback-only server. Some subsystem links are dashed because their caller-to-callee wiring was not shown in the sampled source.
Main entry points: actions_impl.py Workflow actions · retriever.py Hybrid retriever · planner.py Task planner · server.py Loopback HTTP server
Components 25
User interface
- Browser workbench
ui/js/workbench.js - UI state and events
ui/js/store.js - API client
ui/js/api-client.js - Run stream and views
ui/js/stream.js
HTTP service
- Loopback HTTP server
api/server.py - API gateway
api/gateway.py - Intent operations
api/intents.py - Boot and lifecycle
main.py
Planning and agents
- Architect and Coders
agents/architect.py - Laya routing
agents/laya.py - Workflow actions
orchestration/workflow/actions_impl.py - Task planner
orchestration/workflow/planner.py - Workflow worker
orchestration/worker.py - Hybrid retriever
orchestration/retriever.py - Plan parser
crates/deepagents_core/src/parser.rs
Execution and workspace
- Container sandbox
tools/docker_sandbox.py - Shadow workspace
tools/workspace.py - Change staging
tools/staging.py
State and knowledge
- SQLite state and ledger
storage/db.py - Database connections
storage/connection.py - Knowledge graph
storage/graph_engine.py - Vector store
storage/vector_store.py - Semantic index
tools/semantic_index.py
Other components
- User
- Docker daemon
Connections 31
- User → Browser workbench: submits task
- Browser workbench → UI state and events: updates state
- Browser workbench → API client: sends requests
- API client → Loopback HTTP server: calls API
- Loopback HTTP server → API gateway: dispatches requests
api/server.py - API gateway → Intent operations: routes intents
api/server.py - Intent operations → Workflow actions: starts work
- Workflow actions → Laya routing: classifies tasks
orchestration/workflow/actions_impl.py - Workflow actions → Task planner: plans tasks
orchestration/workflow/actions_impl.py - Task planner → Hybrid retriever: retrieves context
orchestration/workflow/planner.py - Hybrid retriever → Semantic index: embeds query
orchestration/retriever.py - Hybrid retriever → Vector store: searches vectors
orchestration/retriever.py - Hybrid retriever → Knowledge graph: traverses graph
orchestration/retriever.py - Task planner → Plan parser: parses plans
- Task planner → Workflow worker: delegates execution
orchestration/workflow/planner.py - Workflow worker → Workflow actions: runs workflow
- Workflow actions → Architect and Coders: invokes agents
orchestration/workflow/actions_impl.py - Workflow actions → Shadow workspace: reads workspace
orchestration/workflow/actions_impl.py - Workflow actions → Container sandbox: executes code
- Container sandbox → Docker daemon: runs containers
- Container sandbox → Shadow workspace: mounts shadow
- Workflow actions → Change staging: stages changes
- User → Change staging: approves merge
- Workflow actions → Database connections: opens state
orchestration/workflow/actions_impl.py - Database connections → SQLite state and ledger: connects SQLite
storage/connection.py - Knowledge graph → SQLite state and ledger: queries tables
storage/graph_engine.py - Hybrid retriever → Database connections: uses connection
orchestration/retriever.py - Hybrid retriever → Run stream and views: returns context
- Loopback HTTP server → Run stream and views: streams run events
- Boot and lifecycle → SQLite state and ledger: migrates schema
main.py - Boot and lifecycle → Loopback HTTP server: starts server