# System Specifications & Technology Stack

GoClaw is a lightweight, high-performance **Autonomous AI Agent Gateway and Multi-Agent Orchestrator** compiled as a single binary. It is engineered to run on consumer hardware, local home servers, and NAS environments.

---

## 1. System Specifications

- **Binary Size:** about 110–155 MB, one self-contained executable (the size depends on the platform).
- **Memory Footprint:** Depends on the workload: browser sessions, document parsing and the memory index use the most.
- **CPU Overhead:** Extremely low idle footprint; spikes during local embedding extraction or concurrent tool runs.
- **External Dependencies:** Zero required runtime runtimes (no Python, Node.js, or Docker required by default, though Docker is supported).
- **Build Requirements:** Requires CGO compilation due to embedded SQLite database and tree-sitter AST parser libraries.

---

## 2. Component Architecture

GoClaw is organized into several logical system boundaries that separate user interactions, agent execution, and system state:

```mermaid
flowchart LR
    CH["<b>Chat Channels</b><br/>Discord, MS Teams, Web, …"] --> GW["<b>AI Gateway</b><br/>WebSocket / REST"]
    GW --> RT["<b>Agent Router</b><br/>Orchestrator"]
    GW --> DB["<b>Session State</b><br/>SQLite / Postgres / MySQL / ClickHouse"]
    RT --> POOL["<b>Agent Pools</b><br/>Isolated Soul / Workspace"]
```

- **Gateway Manager:** Manages real-time WebSocket communication with the Web UI and processes incoming REST API calls and webhooks. Serves an OpenAI-compatible endpoint (`/v1/chat/completions`). Enforces API rate limiting and authenticates requests.
- **Agent Orchestrator:** Manages the lifecycle of multiple independent agents, coordinates message routing, and delegates work to background tasks.
- **State Database:** A flexible persistence engine via GORM supporting SQLite (default, WAL mode), ClickHouse, PostgreSQL, and MySQL. It persists chat sessions, memory, SOPs and their runs, cron jobs, agent traces, token usage and metrics. The credentials `config.yaml` refers to are not kept there: they are in the encrypted vault (`credentials/secrets.enc` in the state directory), and pairings in JSON files. A webhook route made on the Webhooks page keeps its secret and token in the database, as typed (a `${secret:NAME}` reference keeps the value in the vault).
- **RAG & Memory Engine:** Handles document chunking, indexing, and hybrid searches (semantic vectors + keyword) to provide agents with contextual long-term memory.
- **Channel Adapters:** Connects the gateway to messaging platforms (Discord, Microsoft Teams, Facebook Messenger, Telegram) and to mobile or web apps through the App API, and handles session pairing.
- **MCP Client:** Connects agents to external MCP servers (stdio or HTTP) and offers their tools alongside the built-in ones.

---

## 3. Supported Database Engines
GoClaw includes built-in driver layers for both internal state persistence (GORM) and external agent query datasources:

- **SQLite:** Default internal state engine (WAL mode) and local agent query storage.
- **ClickHouse:** High-performance columnar analytics database supported both for internal GORM state/metrics and as an external query datasource.
- **PostgreSQL:** Enterprise relational database supported for internal GORM state and agent queries.
- **MySQL / MariaDB:** Relational database support for internal state and agent queries.
- **MongoDB:** NoSQL document database query support for agents.

---

## 4. Built-in Agent Tools

GoClaw's tools are compiled directly into the binary; `goclaw tools list` lists them. Agents dynamically request access to these tools depending on their allowed roles and current tasks:

| Category | Description | Primary Tools |
|---|---|---|
| **File Operations** | Read, write, search, and patch files in sandboxed workspaces. | `file_read`, `file_write`, `apply_patch`, `glob_files` |
| **Code Analysis** | Generate AST structure maps and analyze source code files. | `repo_map`, `ast_declarations_search`, `dependency_map` |
| **Version Control** | Execute local Git actions and review repository states. | `git`, `auto_commit`, `diff` |
| **Collaboration** | Call GitLab APIs to read issues, pipeline status, and MRs. | `gitlab` |
| **Databases** | Securely query PostgreSQL, MySQL, ClickHouse, and MongoDB. | `db_query`, `mongo_query` |
| **Communication** | Route outgoing messages, alerts, emails, and notifications. | `message`, `email`, `notify` |
| **Memory & RAG** | Read and write from scoped long-term memory. | `memory_search`, `memory_write`, `memory_consolidate` |
| **Web & Automation** | SSRF-safe HTTP calls and headless Chrome browser control. | `http_request`, `browser` (actions: navigate, screenshot, content, click, type, …) |
| **Observability** | Search system logs, traces, APM alerts, and inventory data. | `grafana_alerts`, `graylog_query`, `uptrace_query`, `zabbix_query`, `netbox` |
| **Media & Documents** | Speech-to-text and text-to-speech, read PDFs, and analyze images. | `voice_input` (speech-to-text), `voice_output` (text-to-speech), `pdf`, `image` |
| **Scheduling** | Define and manage automated workflows and periodic jobs. | `cron`, `sop_run`, `sop_save`, `sop_list`, … |

---

## 5. Runtime Concurrency & Execution Limits

To safeguard the host server from resource depletion, GoClaw implements bounded concurrency pools and loop detection parameters:

### Concurrency Allocations

| Parameter | Configuration Key | Default Value | Description |
|---|---|:---:|---|
| **Tool Worker Pool** | `tools.worker_pool_size` | `8` | Maximum number of concurrent tool executions across all sessions. |
| **Backpressure Queue** | `tools.worker_queue_size` | `64` | Depth of the queue holding pending tool executions. |
| **Output Writer** | - | `1` | Single-writer pump per WebSocket connection to guarantee message order. |

### Execution Thresholds

| Parameter | Configuration Key | Default Value | Description |
|---|---|:---:|---|
| **Max Tool Iterations** | `tools.max_tool_iterations` | `20` | Maximum number of continuous tool runs permitted in a single chat turn. Prevents infinite loops. |
| **Result Spill** | `tools.max_result_chars` | `8000` | A tool result longer than this is not passed to the model whole: the full result is kept in the output store for 1 hour and the model gets a preview with a `data_ref`, which it reads further with `read_output`. `db_query` results are always stored this way. |
| **Full Result Rounds** | `tools.full_result_rounds` | `4` | Within one turn, the results of this many newest tool rounds are sent to the model whole; an older result over 2,000 characters is cut to its start and the `read_output` ref that reads it whole. `-1` keeps every result whole. |
| **Dynamic Tools (RAG)** | `tools.rag.top_k` | `12` | Maximum number of dynamically matched tools injected into the prompt. |
| **RAG Threshold** | `tools.rag.min_score` | `0.15` | Minimum matching confidence score required to auto-enable a tool for a query. |

---

## 6. Deployment Models

GoClaw is highly flexible and can be deployed in multiple environments:

- **Standalone Binary:** Compile for target OS (macOS, Linux, Windows) and run directly.
- **Containerized Daemon:** Run using `docker-compose.yaml`. It mounts `./config.yaml` at `/app/config.yaml` and a named volume, `goclaw-state`, on the state directory `/home/goclaw/.goclaw` (database, vault, workspace, logs). The mounted `config.yaml` must set `gateway.bind: lan`, or the gateway listens on the container's loopback and the port mapping reaches nothing. Set `GOCLAW_SECRET_KEY` before the vault is first written: without it the vault key is derived from values that are the same in every container of the image, so anyone with the image can derive it.
- **Ansible Automation:** Deployment playbooks are provided under `/ansible` for multi-node setups.
- **Remote Ingress Tunnel:** Supports built-in Ngrok tunneling to expose the local webhook receiver securely without requiring manual firewall rule modifications.