AgentOS
A self-hosted hub for running independent AI agents as isolated processes — each agent with its own directory, memory, model, tools and network channels, managed from one place.
AgentOS is not a chatbot. It's the layer that creates, launches, monitors and stops your agents. Each agent runs as its own process, in the folder you choose, with its own SQLite memory, its own LLM provider, its own sandboxed toolset, and its own port. The Hub only registers and supervises them — it never centralizes their data.
Personal project, in active development. Built and run daily by the author; two production agents currently run on it (a personal assistant and a legal-tech assistant).
Architecture
┌──────────────────────────────┐
│ Hub (FastAPI, port 8234) │
│ create · launch · monitor │
│ health-check + auto-restart │
└───────────────┬──────────────┘
┌───────────────┬─────────┴───────┬───────────────┐
▼ ▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│ Agent A │ │ Agent B │ │ Agent C │ ...
│ :9001 │ │ :9002 │ │ :9003 │
│ own dir │ │ own dir │ │ own dir │
│ memory.db │ │ memory.db │ │ memory.db │
│ config │ │ config │ │ config │
│ tools/ │ │ tools/ │ │ tools/ │
│ Ollama │ │ OpenAI │ │ Anthropic │
└────────────┘ └────────────┘ └────────────┘
Each agent is spawned from hub/templates/ (LLM adapter, engine, tools, security sandbox, memory, RAG). The Hub reconciles state on restart: agents whose processes are gone are marked offline, and auto_restart ones are brought back.
Features
- Multi-LLM, per agent — Ollama (local models), OpenAI, Anthropic, Google. API keys can be global (inherited) or per-agent.
- Per-agent RAG — local knowledge base per agent (ChromaDB + sentence-transformers), used transparently by the agent's tools.
- MCP interoperability — agents can expose/consume tools over the Model Context Protocol to couple with host programs.
- Network channels, per agent — WhatsApp (Node sidecar) and Telegram (long-polling, no sidecar), enabled individually.
- Sandboxed tools — filesystem and shell tools are restricted to the agent's own directory; path traversal outside the sandbox is blocked.
- Export / import — package an agent as a
.tar.gz (secrets stripped) and restore it elsewhere.
- Health checking — periodic checks with configurable interval/timeout and optional auto-restart.
- Hub auth — optional bearer token on the Hub API; CORS locked to the known UI origins.
Quick start
Requires Python 3.11+. Node.js 18+ is optional (only for the WhatsApp channel). Ollama is optional (only for local models).
git clone https://github.com/r2aistente-cyber/AgentOS.git
cd AgentOS
# macOS / Linux
./install.sh # sets up the venv, installs deps, creates ~/AgentOS/, seeds a first agent
./Iniciar-R2Hub.sh # starts the Hub (:8234), the frontend (:5500) and the desktop window
# Windows
install.bat
Iniciar-R2Hub.bat
The Hub API is then at http://localhost:8234, the UI at http://localhost:5500 (also shown in a native pywebview window). Agents live wherever you place them, not inside the repo.
Configuration is two-level: config.yaml for the Hub, and a config.yaml inside each agent's own directory (personality, provider, tools, channels, sandbox). See SETUP.md.
Tests
pytest -q
~340 automated tests covering the Hub API, the agent manager, the engine, the tool sandbox, RAG, export/import and the template. See pytest.ini.
Project layout
| Path | What |
|---|
hub/ | The Hub — FastAPI app, agent manager, process supervision, health checker, exporter/importer, MCP, channel managers |
hub/api/ | REST endpoints (agents, admin, fs) |
hub/templates/ | The agent blueprint copied into every new agent (engine, LLM adapters, tools, security, memory, RAG, channels) |
frontend/ | Vite + React UI (the live one) |
desktop_shell.py | pywebview window that hosts the UI |
tests/ | Test suite |
examples/ | Sample layout for an agent's knowledge base |
docs/ | Project site (GitHub Pages); docs/vision/ holds forward-looking docs |
desktop/ | Early Tauri prototype — not the current UI |
Tech stack
Python · FastAPI · Uvicorn · Pydantic · SQLite (aiosqlite) · ChromaDB · sentence-transformers · MCP · React · Vite · pywebview · Node (WhatsApp sidecar)
Status & scope
- Designed for single-machine or trusted-LAN use. Set
hub.token to require auth on the Hub API.
- A packaged desktop installer is planned, not shipped — the
desktop/ Tauri app is an early prototype; the current way to run AgentOS is the scripts above. Forward-looking docs live in docs/vision/.
- The design docs (CONCEPTO.md, DESIGN.md, EXPORT.md, INTEGRATION.md) describe the architecture and features; this README is the accurate picture of the current state.
License
MIT © 2026 Javier Enrique Castaño Roldán
