/ README.md
README.md
1 # Ag3ntum: Agentic SysAdmin + DevOps + Webmaster. Sandboxed. 2 3 **Your dedicated Ops Engineer — built with security and safety in mind.** 4 5 <p align="center"> 6 <img src="https://img.shields.io/badge/Python-3.13+-blue.svg" alt="Python 3.13+"> 7 <img src="https://img.shields.io/badge/License-AGPL%20%7C%20Commercial-green.svg" alt="License"> 8 <img src="https://img.shields.io/badge/Security-6%20Layer%20Defense-orange.svg" alt="Security"> 9 <img src="https://img.shields.io/badge/Self--Hosted-Data%20Sovereign-blueviolet.svg" alt="Self-Hosted"> 10 </p> 11 12 Ag3ntum is a self-hosted **agentic platform** for Linux servers and websites. It performs server configuration, security hardening, log analysis, website troubleshooting, and routine maintenance — methodically, traceably, and inside a 6-layer security sandbox. 13 14 Make an API call, schedule recurring tasks, or submit a job through the web UI. Ag3ntum executes with full transparency and domain expertise, reports every step, and requires your approval before making sensitive changes. Full audit trail. Complete session replay. All data stays on your infrastructure. 15 16 **Model-agnostic.** Ships with Anthropic Claude support and a built-in LLM proxy that routes to any OpenAI-compatible API — OpenRouter, Azure OpenAI, Amazon Bedrock (via gateway), Google Vertex AI (via gateway), Ollama, llama.cpp, vLLM, or any local inference server. Swap models per task without code changes. 17 18 <p align="center"> 19 <img src="./docs/artifacts/ag3ntum_ui.gif" alt="Ag3ntum Web UI" width="800"> 20 </p> 21 22 --- 23 24 ## Install 25 26 **Stable release** (recommended): 27 ```bash 28 curl -fsSL https://raw.githubusercontent.com/extractumio/ag3ntum/release/install.sh | bash 29 ``` 30 31 **Latest development** (main branch): 32 ```bash 33 curl -fsSL https://raw.githubusercontent.com/extractumio/ag3ntum/main/install.sh | bash 34 ``` 35 36 Open **http://localhost:50080** after build. See [QUICK-START-GUIDE.md](QUICK-START-GUIDE.md) for API key setup and first user creation. 37 38 **Requirements:** Docker + Docker Compose | 2 GB+ RAM | Linux or macOS 39 40 --- 41 42 ## Capabilities 43 44 ### Server Management 45 46 - **Security hardening** — SSH config audit, firewall review, fail2ban setup, SUID binary scanning, user account audit 47 - **Patch management** — Inventory pending updates, apply with approval, verify services restart cleanly 48 - **Log analysis** — Parse nginx, syslog, auth.log, application logs. Detect anomalies, correlate events, produce actionable summaries 49 - **Health assessment** — Service status, disk/memory/CPU usage, SSL certificate expiry, open port enumeration 50 - **Incident response** — Diagnose outage, identify root cause, apply fix, verify recovery, generate structured report 51 52 ### Website Maintenance 53 54 - **CMS lifecycle** — WordPress/Joomla/Drupal plugin and core updates, compatibility checks, rollback on failure 55 - **Malware remediation** — Scan PHP/JS files for injections, quarantine infections, remove backdoors, harden file permissions 56 - **Database optimization** — Clean transients, optimize tables, identify slow queries, reduce bloat 57 - **SSL management** — Monitor certificate expiry across domains, handle renewals, verify installation 58 - **Performance diagnostics** — Identify bottlenecks, review cache config, analyze resource utilization 59 60 ### DevOps & Infrastructure 61 62 - **Container review** — Docker Compose analysis, resource utilization, image optimization, right-sizing 63 - **Configuration drift** — Compare environments, flag inconsistencies, document differences 64 - **Dependency auditing** — Outdated packages, known CVEs, license compliance 65 - **Deployment support** — Analyze failures, check dependencies, review application logs 66 - **Infrastructure documentation** — Service inventory, port audit, cron job listing, automated system documentation 67 68 ### Document Processing 69 70 Supports document upload and processing directly in the web UI — PDF text extraction, Office documents (DOCX, XLSX, PPTX), archives (ZIP, TAR, 7z), and tabular data (CSV, Excel, Parquet). 71 72 --- 73 74 ## How It Works 75 76 ``` 77 Operator ─── Web UI / REST API ─── Ag3ntum ─── Infrastructure 78 (describe task) (execute) (local mounts, SSH, SFTP) 79 ``` 80 81 1. **Deploy** — Docker Compose on your server. 15 minutes from zero to running. 82 2. **Describe** — State the objective in plain English. No playbooks, no DSL. 83 3. **Observe** — Real-time streaming of every command, output, and decision. 84 4. **Approve** — Destructive operations pause for explicit human confirmation. 85 5. **Audit** — Complete session trail with drill-down into every tool invocation. 86 87 --- 88 89 ## Security Architecture 90 91 Six independent layers of defense-in-depth. Each operates autonomously — compromising one does not weaken the others. 92 93 ``` 94 Request → [WAF] → [Docker] → [Bubblewrap+UID] → [PathValidator] → [CommandFilter] → [SecureOutput] 95 │ │ │ │ │ │ 96 Size limits Container Per-user OS Workspace 140+ blocked Secrets 97 DoS block boundary identity (UID) boundary only patterns auto-redacted 98 ``` 99 100 | Layer | Enforcement | 101 |-------|------------| 102 | **WAF** | Request body size limits, upload filtering, Content-Length spoofing prevention, DoS mitigation | 103 | **Docker** | Container boundary, resource limits, read-only source mount (`:ro`), container-level seccomp profile | 104 | **Bubblewrap + UID** | Per-user Linux UID (50000–60000), PID/IPC/mount namespace isolation, `--clearenv`, per-session seccomp | 105 | **PathValidator** | All file ops restricted to session workspace, symlink escape detection, cross-user access blocked at kernel level | 106 | **Command Filter** | 140+ regex patterns across 16 categories: privilege escalation, destructive ops, container escape, data exfiltration, persistence mechanisms | 107 | **Secure Output** | API keys, tokens, and passwords auto-redacted in file previews and command output. Same-length replacement. | 108 109 ### Containment in practice 110 111 | Vector | Outcome | 112 |--------|---------| 113 | `rm -rf /` | Blocked by command filter before execution | 114 | Read `~/.ssh/id_rsa` | Path not mounted in sandbox — invisible to agent | 115 | `sudo chmod 777 /etc/passwd` | Command filter blocks; seccomp denies at kernel level | 116 | `curl http://169.254.169.254/` | Cloud metadata IP blocked by domain filter | 117 | Cross-user file access | Kernel-enforced UID separation + PathValidator | 118 | Fork bomb `:(){ :\|:& };:` | Command filter + namespace resource limits | 119 | `env` / `printenv` | `--clearenv` strips all host environment variables | 120 121 AI models hallucinate. That is a known property of the technology. Ag3ntum does not solve hallucination — it solves the **blast radius** of hallucination. When the model makes a mistake, the sandbox contains the impact before it reaches your system. 122 123 --- 124 125 ## Multi-Tenant Isolation 126 127 Tenant separation is enforced by the Linux kernel, not application logic. Bypassing the application layer does not grant cross-tenant access. 128 129 | Layer | Mechanism | 130 |-------|-----------| 131 | **OS identity** | Unique Linux UID per user (50000–60000 range), allocated at account creation | 132 | **Filesystem** | Per-session workspace, per-user home directory, 660/770 permissions (no world access) | 133 | **Process** | PID namespace isolation — users cannot enumerate or signal each other's processes | 134 | **Environment** | Per-user API keys and secrets injected into sandbox only, invisible to other tenants | 135 | **Audit** | Complete per-user session history, tamper-resistant (agent cannot modify its own logs) | 136 137 --- 138 139 ## Web Interface 140 141 - **Real-time streaming** — Server-Sent Events with sequence-based deduplication, automatic reconnection with exponential backoff, polling fallback 142 - **Tool call transparency** — Expand any action to inspect exact command, stdin, stdout, stderr, exit code 143 - **File explorer** — Browse workspace files with syntax-highlighted preview, drag-and-drop upload, one-click download 144 - **Human-in-the-loop** — Agent pauses execution and prompts for approval before destructive operations. Answers persist — respond hours later without blocking resources 145 - **Session management** — Full history, resume interrupted sessions, per-session cost and token tracking 146 - **LLM model selection** — Switch models per session via dropdown. Route to any configured provider without restart. 147 148 --- 149 150 ## Platform 151 152 | Feature | Details | 153 |---------|---------| 154 | **Task queue** | Redis-backed priority queue. Default quotas: 4 global concurrent, 2 per user, 50 daily. All configurable. | 155 | **Auto-resume** | Tasks in progress at shutdown automatically resume on container restart | 156 | **Cost tracking** | Per-session input/output/cache token counts with USD cost estimation | 157 | **Checkpoints** | File state captured at each tool invocation — rewind to any previous state | 158 | **Custom skills** | Reusable operation templates (global or per-user), discoverable by the agent at runtime | 159 | **External mounts** | Read-only or read-write host directory access with per-user authorization | 160 | **Dynamic mounts** | Per-session mount requests with allowlist/blocklist authorization and subpath depth limits | 161 | **Custom roles** | Jinja2 prompt templates define agent behavior per deployment or per task | 162 | **LLM proxy** | Built-in multi-provider routing — Anthropic (native), OpenAI, OpenRouter, Azure OpenAI, or any OpenAI-compatible endpoint (Ollama, llama.cpp, vLLM). Configure in YAML. | 163 | **REST API** | Every UI action available programmatically. JWT auth. Full session and event API. | 164 | **Subagents** | Delegate sub-tasks to specialized agents with scoped tool access and isolated context | 165 166 --- 167 168 ## Target Audience 169 170 | Segment | Scale | Primary pain | Ag3ntum value | 171 |---------|-------|-------------|---------------| 172 | **Website operators** | 1–20 sites, WordPress/WooCommerce/Joomla | Midnight outages, malware, plugin conflicts, SSL expiry | Diagnoses and remediates site issues on command. Manages updates. Cleans infections. | 173 | **VPS / server owners** | 3–10 servers, developer-sysadmin hybrid | Patches pile up, logs unchecked, SSH hardening deferred | Handles the maintenance backlog methodically. Patches, audits, hardens — you review results. | 174 | **Hosting companies** | 40+ servers, 500+ customer sites | 3-person ops team bottlenecked on tier-1 operations | Multi-tenant automation with per-customer UID isolation and exportable audit trails. | 175 176 --- 177 178 ## Stack 179 180 | Component | Technology | 181 |-----------|------------| 182 | Runtime | Python 3.13+, FastAPI, Uvicorn | 183 | Frontend | React 18, TypeScript 5.6, Vite | 184 | Database | SQLite (sessions, users, events) | 185 | Cache & Events | Redis 7 (real-time streaming, task queue, rate limiting) | 186 | Sandbox | Bubblewrap, seccomp profiles (3 tiers), Linux namespaces | 187 | Agent Core | Claude Code Agent SDK with 11 custom MCP tools | 188 | LLM Proxy | Multi-provider routing (Anthropic, OpenAI-compatible, OpenRouter) | 189 | Deployment | Docker Compose on Ubuntu 24.04 | 190 191 --- 192 193 ## Quick Reference 194 195 ```bash 196 ./run.sh build # Build image, start all services 197 ./run.sh restart # Restart (picks up code/config changes) 198 ./run.sh rebuild # Full teardown and rebuild 199 ./run.sh create-user # Provision user account with UID allocation 200 ./run.sh test # Run full test suite (backend + security + UI) 201 ./run.sh test --quick # Skip E2E and slow tests 202 ./run.sh shell # Interactive shell into API container 203 ``` 204 205 **After build:** Web UI at `http://localhost:50080` | API at `http://localhost:40080` 206 207 ## Upgrading 208 209 Use `upgrade.sh` for safe, automated upgrades with backup and migration: 210 211 ```bash 212 ./upgrade.sh # Full upgrade: backup, pull, migrate, build, validate 213 ./upgrade.sh --dry-run # Preview changes without modifying anything 214 ./upgrade.sh --check # Health diagnostics only 215 ./upgrade.sh --rollback # Restore from most recent backup 216 ``` 217 218 The upgrade script handles backup creation, dependency change detection, database migration (via Alembic), config schema migration, and post-upgrade health validation. Backups are stored in `backups/` (3 retained). 219 220 **Do not use** `git pull && ./run.sh build` directly — it skips backup, config migration, and dependency change detection. See [docs/how-to-upgrade.md](docs/how-to-upgrade.md) for full details. 221 222 --- 223 224 ## License 225 226 - **AGPL-3.0** — Open source and personal use 227 - **Commercial License** — Hosting companies, SaaS, enterprise deployments 228 229 **Contact:** [info@extractum.io](mailto:info@extractum.io) 230 231 --- 232 233 Built on the <a href="https://platform.claude.com/docs/en/get-started">Claude Code Agent SDK</a>