# extractumio/ag3ntum architecture

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

- Interactive diagram: https://gitdiagram.com/extractumio/ag3ntum
- Repository: https://github.com/extractumio/ag3ntum

## Overview

Ag3ntum is a self-hosted, sandboxed operations agent: an operator submits a task through the web UI or REST API, the platform manages the session and queue, and the agent executes tools against local mounts or remote infrastructure while streaming progress for review and approval. The architecture also includes administration, reseller management, document processing, model routing, and SSH operations. Relationships below follow README statements and SOURCE INDEX references; several subsystems are only represented by their exact enclosing directory because their implementation was not sampled.

Main entry points: [`src/api/main.py`](https://github.com/extractumio/ag3ntum/blob/main/src/api/main.py) (REST API), [`src/services/agent_runner.py`](https://github.com/extractumio/ag3ntum/blob/main/src/services/agent_runner.py) (Agent runner), [`src/core/agent.py`](https://github.com/extractumio/ag3ntum/blob/main/src/core/agent.py) (Agent runtime), [`tools/ag3ntum`](https://github.com/extractumio/ag3ntum/tree/main/tools/ag3ntum) (Agent tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Operator experience"]
  node_webui["Web interface<br/>[App.tsx]"]
  node_clientapi["Client API<br/>[api.ts]"]
  node_adminui["Admin console<br/>[AdminRoutes.tsx]"]
  node_resellerui["Reseller console<br/>[ResellerRoutes.tsx]"]
end

subgraph group_platform["API and orchestration"]
  node_api["REST API<br/>[main.py]"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_sessions["Session service<br/>[session_service.py]"]
  node_queue["Task queue<br/>[task_queue.py]"]
  node_quotas["Queue quotas<br/>[quota_manager.py]"]
  node_events["Session events<br/>[event_service.py]"]
  node_database[("Platform database<br/>[database.py]")]
end

subgraph group_execution["Agent execution"]
  node_runner["Agent runner<br/>[agent_runner.py]"]
  node_agent["Agent runtime<br/>[agent.py]"]
  node_tools["Agent tools"]
  node_sandbox{{"Sandbox and security<br/>[sandbox.py]"}}
  node_documents["Document processing"]
end

subgraph group_operations["Operations and integrations"]
  node_ssh["SSH operations"]
  node_llm["LLM proxy<br/>[llm_proxy.py]"]
end

node_operator(("Operator"))
node_infrastructure[("Managed infrastructure")]

node_operator -->|"describes task"| node_webui
node_webui -->|"submits requests"| node_clientapi
node_clientapi -->|"calls REST API"| node_api
node_api -->|"authenticates"| node_auth
node_api -->|"manages sessions"| node_sessions
node_sessions -->|"reads and writes"| node_database
node_api -->|"starts queue"| node_queue
node_api -->|"initializes quotas"| node_quotas
node_api -->|"dispatches tasks"| node_runner
node_queue -.->|"runs queued tasks"| node_runner
node_runner -->|"runs agent"| node_agent
node_agent -.->|"invokes tools"| node_tools
node_agent -->|"executes isolated"| node_sandbox
node_tools -->|"operates on"| node_infrastructure
node_runner -->|"publishes progress"| node_events
node_events -->|"streams updates"| node_webui
node_operator -->|"manages platform"| node_adminui
node_operator -->|"manages tenants"| node_resellerui
node_api -->|"initializes SSH"| node_ssh
node_ssh -->|"connects remotely"| node_infrastructure
node_api -->|"routes model requests"| node_llm
node_tools -->|"processes uploads"| node_documents

click node_webui "https://github.com/extractumio/ag3ntum/blob/main/src/web_terminal_client/src/App.tsx"
click node_clientapi "https://github.com/extractumio/ag3ntum/blob/main/src/web_terminal_client/src/api.ts"
click node_adminui "https://github.com/extractumio/ag3ntum/blob/main/src/web_terminal_client/src/pages/admin/AdminRoutes.tsx"
click node_resellerui "https://github.com/extractumio/ag3ntum/blob/main/src/web_terminal_client/src/pages/reseller/ResellerRoutes.tsx"
click node_api "https://github.com/extractumio/ag3ntum/blob/main/src/api/main.py"
click node_auth "https://github.com/extractumio/ag3ntum/blob/main/src/services/auth_service.py"
click node_sessions "https://github.com/extractumio/ag3ntum/blob/main/src/services/session_service.py"
click node_queue "https://github.com/extractumio/ag3ntum/blob/main/src/services/task_queue.py"
click node_quotas "https://github.com/extractumio/ag3ntum/blob/main/src/services/quota_manager.py"
click node_events "https://github.com/extractumio/ag3ntum/blob/main/src/services/event_service.py"
click node_database "https://github.com/extractumio/ag3ntum/blob/main/src/db/database.py"
click node_runner "https://github.com/extractumio/ag3ntum/blob/main/src/services/agent_runner.py"
click node_agent "https://github.com/extractumio/ag3ntum/blob/main/src/core/agent.py"
click node_tools "https://github.com/extractumio/ag3ntum/tree/main/tools/ag3ntum"
click node_sandbox "https://github.com/extractumio/ag3ntum/blob/main/src/core/sandbox.py"
click node_documents "https://github.com/extractumio/ag3ntum/tree/main/tools/ag3ntum/ag3ntum_read_document"
click node_ssh "https://github.com/extractumio/ag3ntum/blob/main/src/services/ssh_service_manager.py"
click node_llm "https://github.com/extractumio/ag3ntum/blob/main/src/api/routes/llm_proxy.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_webui,node_clientapi,node_adminui,node_resellerui toneBlue
class node_api,node_auth,node_sessions,node_queue,node_quotas,node_events,node_database,node_infrastructure toneAmber
class node_runner,node_agent,node_tools,node_sandbox,node_documents toneMint
class node_ssh,node_llm toneRose
class node_operator toneIndigo
```

## Components

### Operator experience

- [Web interface](https://github.com/extractumio/ag3ntum/blob/main/src/web_terminal_client/src/App.tsx): `src/web_terminal_client/src/App.tsx`
- [Client API](https://github.com/extractumio/ag3ntum/blob/main/src/web_terminal_client/src/api.ts): `src/web_terminal_client/src/api.ts`
- [Admin console](https://github.com/extractumio/ag3ntum/blob/main/src/web_terminal_client/src/pages/admin/AdminRoutes.tsx): `src/web_terminal_client/src/pages/admin/AdminRoutes.tsx`
- [Reseller console](https://github.com/extractumio/ag3ntum/blob/main/src/web_terminal_client/src/pages/reseller/ResellerRoutes.tsx): `src/web_terminal_client/src/pages/reseller/ResellerRoutes.tsx`

### API and orchestration

- [REST API](https://github.com/extractumio/ag3ntum/blob/main/src/api/main.py): `src/api/main.py`
- [Authentication](https://github.com/extractumio/ag3ntum/blob/main/src/services/auth_service.py): `src/services/auth_service.py`
- [Session service](https://github.com/extractumio/ag3ntum/blob/main/src/services/session_service.py): `src/services/session_service.py`
- [Task queue](https://github.com/extractumio/ag3ntum/blob/main/src/services/task_queue.py): `src/services/task_queue.py`
- [Queue quotas](https://github.com/extractumio/ag3ntum/blob/main/src/services/quota_manager.py): `src/services/quota_manager.py`
- [Session events](https://github.com/extractumio/ag3ntum/blob/main/src/services/event_service.py): `src/services/event_service.py`
- [Platform database](https://github.com/extractumio/ag3ntum/blob/main/src/db/database.py): `src/db/database.py`

### Agent execution

- [Agent runner](https://github.com/extractumio/ag3ntum/blob/main/src/services/agent_runner.py): `src/services/agent_runner.py`
- [Agent runtime](https://github.com/extractumio/ag3ntum/blob/main/src/core/agent.py): `src/core/agent.py`
- [Agent tools](https://github.com/extractumio/ag3ntum/tree/main/tools/ag3ntum): `tools/ag3ntum`
- [Sandbox and security](https://github.com/extractumio/ag3ntum/blob/main/src/core/sandbox.py): `src/core/sandbox.py`
- [Document processing](https://github.com/extractumio/ag3ntum/tree/main/tools/ag3ntum/ag3ntum_read_document): `tools/ag3ntum/ag3ntum_read_document`

### Operations and integrations

- [SSH operations](https://github.com/extractumio/ag3ntum/blob/main/src/services/ssh_service_manager.py): `src/services/ssh_service_manager.py`
- [LLM proxy](https://github.com/extractumio/ag3ntum/blob/main/src/api/routes/llm_proxy.py): `src/api/routes/llm_proxy.py`

### Other components

- **Operator**
- **Managed infrastructure**

## Connections

- Operator → Web interface: describes task
- Web interface → Client API: submits requests (evidence: `src/web_terminal_client/src/App.tsx`)
- Client API → REST API: calls REST API
- REST API → Authentication: authenticates
- REST API → Session service: manages sessions (evidence: `src/api/main.py`)
- Session service → Platform database: reads and writes (evidence: `src/services/session_service.py`)
- REST API → Task queue: starts queue (evidence: `src/api/main.py`)
- REST API → Queue quotas: initializes quotas (evidence: `src/api/main.py`)
- REST API → Agent runner: dispatches tasks (evidence: `src/api/main.py`)
- Task queue → Agent runner: runs queued tasks
- Agent runner → Agent runtime: runs agent (evidence: `src/services/agent_runner.py`)
- Agent runtime → Agent tools: invokes tools
- Agent runtime → Sandbox and security: executes isolated
- Agent tools → Managed infrastructure: operates on
- Agent runner → Session events: publishes progress (evidence: `src/services/agent_runner.py`)
- Session events → Web interface: streams updates
- Operator → Admin console: manages platform (evidence: `src/web_terminal_client/src/pages/admin/AdminRoutes.tsx`)
- Operator → Reseller console: manages tenants (evidence: `src/web_terminal_client/src/pages/reseller/ResellerRoutes.tsx`)
- REST API → SSH operations: initializes SSH (evidence: `src/api/main.py`)
- SSH operations → Managed infrastructure: connects remotely
- REST API → LLM proxy: routes model requests (evidence: `src/api/routes/llm_proxy.py`)
- Agent tools → Document processing: processes uploads
