# agentlas-ai/agentlas-os architecture

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

- Interactive diagram: https://gitdiagram.com/agentlas-ai/agentlas-os
- Repository: https://github.com/agentlas-ai/agentlas-os

## Overview

#### Purpose and entry points
Agentlas OS is a local-first, model-neutral agent operating layer. It compiles portable agent/team packages, discovers local/private/public agents, executes through the user’s host runtime, and records verification evidence. Primary shell entry points are `bin/hephaestus`, `bin/hep-build`, `bin/hep-network`, `bin/hep-storm`, `bin/hep-cloud`, and `bin/ontology`; Python entry points include `agentlas_cloud/__main__.py`, `ontology/__main__.py`, and `career_graph/__main__.py`.

#### Host adapters and distribution boundary
The canonical engine is Python plus shell launchers; host-specific command/skill surfaces are thin adapters rather than separate engines. Claude, Codex, Gemini, Cursor, Antigravity, OpenCode, and others receive runtime-specific plugins, commands, hooks, and workflow files. The substantial duplicated trees under `claude/plugins/agentlas-core-engine-meta-agent/` and `codex/plugins/agentlas-core-engine-meta-agent/` are packaged runtime copies of core assets; treat root `agentlas_cloud/`, `ontology/`, schemas, templates, and `bin/` as the likely source-side architecture.

Key paths: `scripts/install-all-runtimes.sh`, `scripts/sync-adapters.sh`, `.claude/commands/agentlas.md`, `codex/prompts/agentlas.md`.

#### Build pipeline and package contracts
The Meta-Agent Factory turns a natural-language request into a single agent, a team, or a distributable package. It first shapes requirements through the interview subsystem, then compiles package artifacts, routing information, contracts, and reusable templates. Package validity is structural: schemas and verification scripts enforce required artifacts rather than trusting model output.

Key paths: `agentlas_cloud/interview/directive.py`, `agentlas_cloud/interview/scorer.py`, `agentlas_cloud/brief/compile.py`, `agentlas_cloud/package_contract.py`, `schemas/agentlas-brief.schema.json`, `templates/agent-card.json.tpl`.

#### Agent graph, routing, and A2A boundary
Agent definitions are loaded, migrated, validated, cataloged, and queried as an agent graph. Routing uses cards/contracts and supports A2A import/export and caller-gated invocation. This is the core portability boundary: packages express methods and runtime requirements, while the current host owns credentials, tools, permissions, and actual model execution.

Key paths: `agentlas_cloud/agent_graph/kernel.py`, `agentlas_cloud/agent_graph/loader.py`, `agentlas_cloud/agent_graph/validator.py`, `agentlas_cloud/agent_graph/a2a.py`, `agentlas_cloud/global_router.py`.

#### Workforce federation and execution
Network orchestration federates exact source scopes—local registry, owner Cloud, and public Hub—then validates host-authored staffing selection before preparing pinned releases. The execution fabric runs plans with policy/approval checks, journals progress, and produces receipts. Stormbreaker supplies the bounded decomposition, repair, and final verification gate.

Key paths: `agentlas_cloud/workforce/selection.py`, `agentlas_cloud/workforce/execution.py`, `agentlas_cloud/networking/router.py`, `agentlas_cloud/networking/execution_fabric.py`, `agentlas_cloud/networking/stormbreaker_runner.py`, `agentlas_cloud/networking/run_journal.py`.

#### Cloud, Hub, research, and updates
Cloud/Hub integration is a package transport and discovery layer, not server-side LLM execution. Authenticated clients invoke remote catalog/bundle operations with fallbacks; upload and repair flows manage package transfer. Research is an adapter-based acquisition subsystem with browser, HTTP, search, GitHub, RSS, Jina, and social-platform integrations, bounded by policy, credentials, redaction, evidence scoring, and receipts. Runtime updates are separate background/install concerns.

Key paths: `agentlas_cloud/networking/hub_client.py`, `agentlas_cloud/networking/hub_invocation.py`, `agentlas_cloud/upload.py`, `agentlas_cloud/research/engine.py`, `agentlas_cloud/research/adapters/`, `agentlas_cloud/update.py`.

#### Local knowledge and governed memory
The ontology runtime ingests local documents into SQLite/FTS-backed retrieval with parser adapters, local embeddings, ranking, and graph-oriented retrieval. Governed memory separates contracts/hooks/import from federated memory and experience privacy controls; it is delivered to hosts through runtime hooks without making cloud search a source of local project content. Bundled Model2Vec assets enable offline semantic vectors.

Key paths: `ontology/runtime.py`, `ontology/parsers.py`, `ontology/embeddings.py`, `agentlas_cloud/memory_contract.py`, `agentlas_cloud/memory_hook.py`, `assets/model2vec/potion-base-8M-int8/manifest.json`.

Main entry points: [`agentlas_cloud/global_router.py`](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/global_router.py) (Global router), [`agentlas_cloud/agent_graph/kernel.py`](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/agent_graph/kernel.py) (Agent graph kernel), [`scripts/install-all-runtimes.sh`](https://github.com/agentlas-ai/agentlas-os/blob/main/scripts/install-all-runtimes.sh) (Host adapters), [`agentlas_cloud/brief/compile.py`](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/brief/compile.py) (Brief compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hosts["Host Distribution"]
  node_host_adapters["Host adapters<br/>runtime adapters"]
  node_adapter_sync["Adapter sync<br/>distribution script<br/>[sync-adapters.sh]"]
end

subgraph group_factory["Package Factory"]
  node_interview["Requirements interview<br/>interview subsystem<br/>[directive.py]"]
  node_brief_compiler["Brief compiler<br/>package compiler<br/>[compile.py]"]
  node_package_contract["Package contract<br/>structural validation"]
  node_brief_schema["Brief schema<br/>JSON Schema"]
  node_agent_template["Agent card template<br/>artifact template"]
end

subgraph group_core["Agent Runtime"]
  node_agent_kernel["Agent graph kernel<br/>[kernel.py]"]
  node_agent_validator["Agent validator<br/>validation<br/>[validator.py]"]
  node_a2a_boundary["A2A import/export<br/>portability boundary<br/>[a2a.py]"]
  node_global_router["Global router<br/>routing<br/>[global_router.py]"]
end

subgraph group_federation["Federation &amp; Execution"]
  node_staffing_selection["Workforce selection<br/>staffing policy<br/>[selection.py]"]
  node_network_router["Network router<br/>federation router<br/>[router.py]"]
  node_execution_fabric["Execution fabric<br/>plan runner"]
  node_stormbreaker["Stormbreaker<br/>verification gate"]
  node_run_journal[("Run journal<br/>execution evidence<br/>[run_journal.py]")]
  node_hub_client["Cloud/Hub transport<br/>package transport<br/>[hub_client.py]"]
end

subgraph group_knowledge["Local Knowledge &amp; Memory"]
  node_research_engine["Research engine<br/>acquisition subsystem<br/>[engine.py]"]
  node_ontology_runtime[("Ontology runtime<br/>local retrieval<br/>[runtime.py]")]
  node_memory_hook["Governed memory hook<br/>host memory delivery<br/>[memory_hook.py]"]
end

node_adapter_sync -->|"installs and syncs"| node_host_adapters
node_host_adapters -->|"invokes"| node_global_router
node_interview -->|"shapes requirements"| node_brief_compiler
node_brief_compiler -->|"produces package"| node_package_contract
node_brief_schema -.->|"defines brief validity"| node_package_contract
node_agent_template -.->|"renders card artifacts"| node_brief_compiler
node_package_contract -->|"admits valid definitions"| node_agent_kernel
node_agent_kernel -->|"validates graph"| node_agent_validator
node_agent_kernel -->|"imports and exports"| node_a2a_boundary
node_agent_validator -->|"supplies validated agents"| node_global_router
node_a2a_boundary -->|"exposes portable contracts"| node_global_router
node_global_router -->|"requests staffing"| node_staffing_selection
node_staffing_selection -->|"approved source selection"| node_network_router
node_hub_client -->|"remote catalog and bundles"| node_network_router
node_network_router -->|"prepares pinned releases"| node_execution_fabric
node_execution_fabric -->|"executes bounded work"| node_stormbreaker
node_stormbreaker -->|"verification evidence"| node_run_journal
node_research_engine -.->|"research receipts"| node_run_journal
node_ontology_runtime -->|"local retrieval context"| node_memory_hook
node_memory_hook -->|"delivers host hooks"| node_host_adapters

click node_host_adapters "https://github.com/agentlas-ai/agentlas-os/blob/main/scripts/install-all-runtimes.sh"
click node_adapter_sync "https://github.com/agentlas-ai/agentlas-os/blob/main/scripts/sync-adapters.sh"
click node_interview "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/interview/directive.py"
click node_brief_compiler "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/brief/compile.py"
click node_package_contract "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/package_contract.py"
click node_brief_schema "https://github.com/agentlas-ai/agentlas-os/blob/main/schemas/agentlas-brief.schema.json"
click node_agent_template "https://github.com/agentlas-ai/agentlas-os/blob/main/templates/agent-card.json.tpl"
click node_agent_kernel "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/agent_graph/kernel.py"
click node_agent_validator "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/agent_graph/validator.py"
click node_a2a_boundary "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/agent_graph/a2a.py"
click node_global_router "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/global_router.py"
click node_staffing_selection "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/workforce/selection.py"
click node_network_router "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/networking/router.py"
click node_execution_fabric "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/networking/execution_fabric.py"
click node_stormbreaker "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/networking/stormbreaker_runner.py"
click node_run_journal "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/networking/run_journal.py"
click node_hub_client "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/networking/hub_client.py"
click node_research_engine "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/research/engine.py"
click node_ontology_runtime "https://github.com/agentlas-ai/agentlas-os/blob/main/ontology/runtime.py"
click node_memory_hook "https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/memory_hook.py"

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_host_adapters,node_adapter_sync toneBlue
class node_interview,node_brief_compiler,node_package_contract,node_brief_schema,node_agent_template toneAmber
class node_agent_kernel,node_agent_validator,node_a2a_boundary,node_global_router toneMint
class node_staffing_selection,node_network_router,node_execution_fabric,node_stormbreaker,node_run_journal,node_hub_client toneRose
class node_research_engine,node_ontology_runtime,node_memory_hook toneIndigo
```

## Components

### Host Distribution

- [Host adapters](https://github.com/agentlas-ai/agentlas-os/blob/main/scripts/install-all-runtimes.sh): runtime adapters · Thin commands, plugins, hooks, and workflows for supported hosts. · `scripts/install-all-runtimes.sh`
- [Adapter sync](https://github.com/agentlas-ai/agentlas-os/blob/main/scripts/sync-adapters.sh): distribution script · Installs and synchronizes packaged host surfaces. · `scripts/sync-adapters.sh`

### Package Factory

- [Requirements interview](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/interview/directive.py): interview subsystem · `agentlas_cloud/interview/directive.py`
- [Brief compiler](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/brief/compile.py): package compiler · Builds agents, teams, routes, contracts, and artifacts. · `agentlas_cloud/brief/compile.py`
- [Package contract](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/package_contract.py): structural validation · Enforces required package artifacts rather than trusting model output. · `agentlas_cloud/package_contract.py`
- [Brief schema](https://github.com/agentlas-ai/agentlas-os/blob/main/schemas/agentlas-brief.schema.json): JSON Schema · `schemas/agentlas-brief.schema.json`
- [Agent card template](https://github.com/agentlas-ai/agentlas-os/blob/main/templates/agent-card.json.tpl): artifact template · `templates/agent-card.json.tpl`

### Agent Runtime

- [Agent graph kernel](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/agent_graph/kernel.py): agent graph · Loads, migrates, catalogs, and queries portable agent definitions. · `agentlas_cloud/agent_graph/kernel.py`
- [Agent validator](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/agent_graph/validator.py): validation · `agentlas_cloud/agent_graph/validator.py`
- [A2A import/export](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/agent_graph/a2a.py): portability boundary · Exchanges cards and contracts while the host retains execution authority. · `agentlas_cloud/agent_graph/a2a.py`
- [Global router](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/global_router.py): routing · Selects agents using cards, contracts, and caller-gated invocation. · `agentlas_cloud/global_router.py`

### Federation & Execution

- [Workforce selection](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/workforce/selection.py): staffing policy · Federates local, owner Cloud, and public Hub scopes into host-approved staffing. · `agentlas_cloud/workforce/selection.py`
- [Network router](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/networking/router.py): federation router · `agentlas_cloud/networking/router.py`
- [Execution fabric](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/networking/execution_fabric.py): plan runner · Runs approved plans with policy checks and pinned releases. · `agentlas_cloud/networking/execution_fabric.py`
- [Stormbreaker](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/networking/stormbreaker_runner.py): verification gate · Performs bounded decomposition, repair, and final verification. · `agentlas_cloud/networking/stormbreaker_runner.py`
- [Run journal](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/networking/run_journal.py): execution evidence · Records progress and receipts. · `agentlas_cloud/networking/run_journal.py`
- [Cloud/Hub transport](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/networking/hub_client.py): package transport · Authenticated catalog and bundle operations with fallbacks. · `agentlas_cloud/networking/hub_client.py`

### Local Knowledge & Memory

- [Research engine](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/research/engine.py): acquisition subsystem · Policy-bounded adapter research with evidence scoring and receipts. · `agentlas_cloud/research/engine.py`
- [Ontology runtime](https://github.com/agentlas-ai/agentlas-os/blob/main/ontology/runtime.py): local retrieval · Indexes local documents into SQLite/FTS retrieval with embeddings and graph-oriented ranking. · `ontology/runtime.py`
- [Governed memory hook](https://github.com/agentlas-ai/agentlas-os/blob/main/agentlas_cloud/memory_hook.py): host memory delivery · Delivers contracts and privacy-governed federated memory through host hooks. · `agentlas_cloud/memory_hook.py`

## Connections

- Adapter sync → Host adapters: installs and syncs
- Host adapters → Global router: invokes
- Requirements interview → Brief compiler: shapes requirements
- Brief compiler → Package contract: produces package
- Brief schema → Package contract: defines brief validity
- Agent card template → Brief compiler: renders card artifacts
- Package contract → Agent graph kernel: admits valid definitions
- Agent graph kernel → Agent validator: validates graph
- Agent graph kernel → A2A import/export: imports and exports
- Agent validator → Global router: supplies validated agents
- A2A import/export → Global router: exposes portable contracts
- Global router → Workforce selection: requests staffing
- Workforce selection → Network router: approved source selection
- Cloud/Hub transport → Network router: remote catalog and bundles
- Network router → Execution fabric: prepares pinned releases
- Execution fabric → Stormbreaker: executes bounded work
- Stormbreaker → Run journal: verification evidence
- Research engine → Run journal: research receipts
- Ontology runtime → Governed memory hook: local retrieval context
- Governed memory hook → Host adapters: delivers host hooks