ATOM Platform

Open-Source AI Agent Platform for Self-Hosted Automation

Developer Note: For technical setup and architecture, see docs/development/overview.md.

Automate your workflows by talking to an AI — and let it remember, search, and handle tasks like a real assistant.

What is Atom?

Atom is an open-source, self-hosted AI agent platform that combines visual workflow builders with intelligent LLM-based agents.

Just speak or type your request, and Atom's specialty agents will plan, verify, and execute complex workflows across your entire tech stack.

Key Difference: Atom is self-hosted — your workflow data, agent state, and memory stay on your infrastructure. LLM inference uses your own API keys (BYOK) with cloud providers (OpenAI, Anthropic, DeepSeek); local model support (Ollama, Llama.cpp) is available for fully private deployments.

Comparing alternatives? See Atom vs OpenClaw for a detailed feature comparison.

Atom vs OpenClaw: Quick Comparison

Aspect	Atom	OpenClaw
Best For	Business automation, multi-agent workflows	Personal productivity, messaging workflows
Agent Model	Multi-agent system with specialty agents	Single-agent runtime
Governance	✅ 4-tier maturity (Student → Autonomous)	❌ No maturity levels
Memory	✅ Episodic memory + per-turn fact extraction + agent memory tools	✅ Persistent Markdown files
Integrations	46+ business (CRM, support, dev tools)	50+ personal (smart home, media, messaging)
Office Automation	✅ Real-time Excel/Word/PPTX co-editing on Canvas	❌ None
Architecture	Python + FastAPI + PostgreSQL/SQLite	Node.js + local filesystem
Setup	Docker Compose (~15-30 min)	Single script (~10-30 min)

Full Comparison →

Atom vs Hermes Agent: Quick Comparison

Hermes (Nous Research) is an open-source personal agent known for its memory-provider architecture. Atom adopted its strongest ideas (per-turn fact extraction, pre-compression hooks, circuit breaker, FTS5 search) and deliberately avoided its weakest (custom LLM-summarizing compressor — Hermes' own has 3 documented production bugs).

Aspect	Atom	Hermes Agent
Best For	Business automation, governed multi-agent workflows	Personal coding/productivity assistant
Memory extraction	✅ Per-turn durable-fact extraction (5 categories, Mem0 taxonomy)	✅ Memory-provider ABC with 7 hooks (reference design)
Context compression	✅ Boundary protection + tool-pair sanitization (deterministic only)	◐ 4-phase compressor incl. LLM summary (3 documented bugs)
Agent memory tools	✅ `memory_remember` / `memory_forget` (maturity-gated)	✅ `lancedb_remember` / `mem0_*` tool family
Governance	✅ 4-tier maturity (Student → Autonomous) + HITL supervision	❌ None
Multi-agent	✅ Queen + Fleet Admiral + specialty agents	❌ Single agent loop
Canvas / rich UI	✅ 7 canvas types, WebSocket, a11y	❌ Terminal + messaging
Office Automation	✅ Real-time Excel/Word/PPTX co-editing on Canvas	❌ None
Cost routing	✅ 5-tier cognitive classification	◐ Aux-model only
Observability	✅ Prometheus + `/health/*` + structlog	❌ WARNING logs
Retrieval	Tier-1 SQL + Tier-2 vector + FTS5 lexical	Vector + BM25 hybrid + cross-encoder reranker
Circuit breaker	✅ 5 failures → 120s cooldown → half-open probe	✅ 2-min/5-failure (fixed window)
Deployment	Python + FastAPI + SQLite/PostgreSQL + embedded LanceDB	Python self-hosted + embedded LanceDB

Full Comparison → · Context Memory Design →

Architecture

Single-Tenant Deployment

Atom is designed for self-hosted deployment:

Simpler Setup: No tenant isolation, no subdomain routing
Better Performance: Direct database access without overhead
Self-Hosted: Agent state, memory, and workflow data stay on your infrastructure. LLM prompts are sent to your configured API provider (BYOK). Use local models (Ollama/Llama.cpp) for fully private setups.
Unlimited Usage: No subscription fees or quota limits

Key Features:

Uses user_id for user identification
No billing system or quota enforcement
Fleet recruitment limited by system resources only
All governance, routing, and graduation features work identically

Full Architecture Guide →

Data Flow & Privacy

Understanding where your data goes:

Component	Where Data Goes	Configurable?
LLM inference (chat, reasoning, agent decisions)	Cloud API provider via your BYOK keys (OpenAI, Anthropic, DeepSeek)	✅ Use local models (Ollama, Llama.cpp) for fully private
Embeddings (document vectors)	Local (FastEmbed, ONNX runtime)	Always local
Vector storage (episodic memory)	Local (LanceDB on disk)	Always local
Database (agents, users, workflows)	Local (SQLite) or your PostgreSQL server	Always your infra
File uploads	Local filesystem (`./data/`)	Always your infra
Integration data (Slack, Gmail, etc.)	Third-party APIs per integration	Per-integration

For maximum privacy: Set ATOM_LOCAL_ONLY=true (blocks cloud integrations) AND configure local LLM models (Ollama/Llama.cpp) instead of cloud API keys.

Meta-Agent Routing ✨

Intelligent CHAT/WORKFLOW/TASK routing with governance checks and dynamic fleet recruitment

Meta-Agent Guide →

Self-Healing & Harness Evolution 🛡️

Offline weakness mining scans execution traces to identify model-specific failure profiles, validation gating runs regression tests inside temporary copy-on-write sandboxes, and commits auto-mutated patches (AST tripwire rules, prompt guidance, context bounds) directly to agent configurations.

Self-Evolving Harness Guide →

Quick Start

The fastest path to a running local server (verified working June 2026):

git clone https://github.com/rush86999/atom.git
cd atom

# Backend deps in a venv
cd backend
python3.11 -m venv venv
./venv/bin/pip install -r requirements.txt

# Frontend deps
cd ../frontend-nextjs
npm install --legacy-peer-deps
cd ..

# Configure — copy the template (every var has a working default; you only
# need to set SECRET_KEY + one LLM key). Full reference:
#   docs/reference/ENVIRONMENT_VARIABLES.md
cp backend/.env.example backend/.env
# Edit backend/.env — generate SECRET_KEY with: openssl rand -base64 48
# ...and set OPENAI_API_KEY=sk-... (or ATOM_LOCAL_ONLY=true for Ollama)

# Point the frontend at the backend (port 8001 in the commands below)
cat > frontend-nextjs/.env.local <<'EOF'
NEXT_PUBLIC_API_URL=http://localhost:8001
NEXT_PUBLIC_USE_BACKEND_API=true
EOF

# ▶️ Launch the FULL app (recommended — all 40+ routers, the real feature
#    surface used in production and by the E2E suite). Run from the repo root.
PYTHONPATH=$PWD:$PWD/backend \
  DISABLE_AUTH_RATE_LIMIT=1 \
  ./backend/venv/bin/python -m uvicorn main_api_app:app --reload --port 8001

# In a second terminal: frontend
cd frontend-nextjs && npm run dev -- -p 3001

Frontend (UI): http://localhost:3001
Backend API: http://localhost:8001
API docs (Swagger): http://localhost:8001/docs
Health check: http://localhost:8001/alive

DISABLE_AUTH_RATE_LIMIT=1 only lifts the registration rate-limit so you can create test users freely; it does not change the database. Remove it for any shared/production deployment.

Minimal app (smoke only): minimal_app.py boots a ~125-route subset for fast checks — uvicorn minimal_app:app --port 8000. It lacks skills, marketplace, workflows, canvas, integrations, etc. Use main_api_app:app (above) to actually use Atom.

That's it! 🚀

Choose your edition:

Personal Edition (default) — Free, single-user, SQLite, zero external services
Enterprise Edition — Multi-user, PostgreSQL, monitoring (set DATABASE_URL to a Postgres DSN)

Verify your setup with the E2E journey suite (boots both apps and walks the full UI + API): see backend/tests/e2e_ui/JOURNEY_TESTS.md.

For alternative paths (Docker, DigitalOcean 1-click) and the full walkthrough, see:

Quick Start (verified) ⭐ — step-by-step with troubleshooting
First Steps after install — what to do once the server is running
Troubleshooting — common errors and fixes
Full Installation Guide — all installation variants
Development Setup — for contributors

Common tasks (`make`)

A Makefile wraps the canonical commands so you don't have to remember them:

make setup          # one-shot dev bootstrap (venv, deps, .env, frontend install)
make backend        # run the full backend (main_api_app) on :8001
make frontend       # run the frontend dev server on :3001
make test-e2e       # run the E2E journey suite (needs both apps running)
make docker-build   # build the dual-app Docker image
make help           # list every target

Repository layout

atom/
├── backend/            # FastAPI app — run main_api_app:app (full) or minimal_app:app (smoke)
├── frontend-nextjs/    # Next.js web UI
├── mobile/             # React Native (Expo) companion app
├── menubar/            # Tauri macOS menubar companion
├── scripts/            # ~6 canonical scripts (quickstart, dev, e2e stack, docker entrypoint)
├── infra/              # deployment recipes (terraform, aws, reference compose files)
├── installer/          # bare-metal native install scripts
├── docs/               # project documentation
├── examples/           # standalone demo scripts
├── archive/            # superseded files (kept for history; nothing here is referenced)
├── Dockerfile          # dual-app image (backend + frontend) — what CI builds
├── docker-compose.yml  # local/prod stack (postgres + backend + frontend + piece-engine)
└── Makefile            # common tasks (start here)

The full app (backend/main_api_app.py) is the canonical entrypoint — all 40+ routers, the real feature surface, what Docker/CI/the E2E suite use. The minimal backend/minimal_app.py (~125 routes) exists only as a fast smoke bootstrap.

Key Features

🎙️ Voice Interface

Build complex workflows using just your voice
Natural language understanding — no proprietary syntax
Real-time feedback as Atom visualizes its reasoning

🤖 Specialty Agents & Orchestration ✨ Enhanced 2026

Sales, Marketing, Engineering: CRM pipelines, campaigns, deployments, incidents
Hive Orchestration: Queen Agent (structured workflows) and FleetAdmiral (dynamic recruitment)
Conductor Agent: 5 execution strategies (SEQUENTIAL, PARALLEL, HYBRID, ADAPTIVE, ROLLBACK_SAFE)
Workflow State Machine: Validated transitions with automatic rollback
Event Bus: Event-driven workflow triggering with pub/sub
Self-Evolving Capabilities: Memento Skills learns from failures, AlphaEvolver optimizes via mutation

Queen Agent → | Auto-Dev →

🎨 Canvas Presentations & Real-Time Guidance ✨

Rich interactive presentations (charts, forms, markdown) with live operation visibility, multi-view orchestration, smart error resolution, and AI accessibility (canvas state exposed to agents). Canvases live both in chat and in a dedicated standalone workspace at /canvas with full CRUD, a side-chat agent co-editor, and version history.

Canvas Guide → | Office Automation Guide →

💼 Office Automation & Document Co-Editing ✨

Real-Time Collaboration: Co-edit Excel spreadsheets, Word documents, and PowerPoint presentations directly on the interactive Canvas.
AI-Driven Office Workflows: Automate document generation, spreadsheet analysis, formatting, and reporting through voice or chat.
Agent Integration: Full synchronization between agent actions and document state for autonomous office task execution.

Office Automation Guide →

🧠 Autonomous Self-Evolution & Graduation ✨

Experience-based learning with recursive self-evolution, dual-trigger graduation (SUPERVISED → AUTONOMOUS), and hybrid PostgreSQL + LanceDB storage

Agent Graduation Guide →

💾 Memory & Context (Hermes-style) ✨ New 2026

Durable-fact extraction layer that survives context compression — the agent remembers what matters across sessions:

Per-turn extraction: 5 durable-fact categories (exact values, hard constraints, decision reasoning, cross-task deps, implicit preferences) extracted fire-and-forget after each ReAct step
Two-tier recall: Tier-1 pure-SQL DURABLE FACTS prompt block (sub-ms) + Tier-2 LanceDB semantic recall (opt-in) + FTS5 lexical fallback for exact-match queries
Agent memory tools: memory_remember / memory_forget let the agent explicitly persist or invalidate facts mid-turn (maturity-gated, deletion-safe)
Pre-compression queue: drains prompts before truncation drops facts (strictly additive, default ON)
Circuit breaker: 5 failures → 120s cooldown → half-open probe (prevents extraction storms)
Boundary-protection compression: head + tail preserved, stale middle elided (deterministic; no buggy LLM-summary phase)

Context Memory Design → · Atom vs. Hermes →

🛡️ Agent Governance System ✨ Enhanced 2026

4-tier maturity: Student → Intern → Supervised → Autonomous
Three-layer governance: OPERATIONAL (<10ms), TACTICAL (<100ms), STRATEGIC (human-in-the-loop)
Policy engine: Context-aware evaluation with priority resolution
AI-powered training: Duration estimation with historical data
Complete audit trail: Every action logged, timestamped, and traceable

Governance Documentation → | Enhancement Plan →

🔌 Deep Integrations

46+ business integrations: Slack, Gmail, HubSpot, Salesforce, Zendesk
9 messaging platforms: Real-time communication
Marketplace Connection: Access 5,000+ community skills and agent templates ✨ NEW
Use /run, /workflow, /agents from your favorite chat app

🔍 Knowledge Graph & GraphRAG ✨ Enhanced 2026

Recursive knowledge retrieval via BFS traversal, canonical anchoring to database records, bidirectional sync, and D3-powered visual explorer

Multi-Hop Expansion: Cue-driven activation for entity relationships — wired into the production local_search path (scored, prioritized multi-hop paths via SQLMultiHopExpander)
Dynamic Graph Construction: Incremental updates without full rebuilds
Enhanced Community Detection: Leiden algorithm clustering (with Louvain fallback) — wired into GraphRAGEngine.build_communities, populating the graph_communities table for global search

GraphRAG Documentation →

🌐 Community Skills & Package Marketplace ✨

5,000+ OpenClaw/ClawHub skills with PostgreSQL marketplace, LLM-powered security scanning (21+ malicious patterns), DAG skill composition, Python + npm auto-installation with vulnerability scanning, and supply chain protection

Community Skills Guide → | Python Packages → | npm Packages →

🔍 Browser & Device Automation

Browser automation via CDP (scraping, form filling)
Device control (camera, location, notifications)
Maturity-governed for security
Pre-action match-confidence ✨ — selectors scored high/partial/ambiguous before clicking; partial/ambiguous route through human review even for AUTONOMOUS agents. See Match-Confidence Layer

🐝 Swarm Coordination ✨ New 2026

Four advanced multi-agent coordination patterns (derived from Cursor's swarm research + domain-aware verification literature) that address failure modes when many agents operate concurrently on shared codebases:

Stigmergic Field Guide: per-workspace Markdown memory that agents read and write — runtime rules discovered during execution persist into every agent's system prompt. Backed by PostgreSQL (field_guides table, pod-restart safe) with a filesystem fallback for local dev.
Domain-Aware Verification Cascade: 2-stage CODE pipeline that verifies agent outputs using domain-specific strategies (formal, grounded, schema, execution-backed).
Megafile Tripwire & Branch Reconciler: sandbox tripwires that detect runaway file growth and reconcile divergent agent branches before merge.

Swarm Coordination Architecture →

🚀 2026 Enhancement Plan

Based on cutting-edge 2025-2026 AI research, Atom has been enhanced with 5 major feature phases:

Phase 1: Memory & Graduation ✅ Complete

POMDP memory framework for experience-driven learning
Offline memory consolidation (inspired by human sleep)
Quality-weighted graduation criteria (20% improvement)

Phase 2: GraphRAG Enhancement ✅ Complete

Multi-hop expansion with cue-driven activation
Dynamic graph construction (incremental updates)
Enhanced community detection (Leiden algorithm)

Phase 3: Learning-Based LLM Routing ✅ Complete

Per-model satisfaction predictors that re-rank BPC candidates from observed outcomes
DB-persisted feedback (llm_routing_feedback), live /api/chat/feedback, quality signals
Model visibility badge on chat responses + routing dashboard at /settings/routing
Flag-gated (ATOM_LEARNING_ROUTER, default off) — augments, doesn't replace, the Cognitive Tier System
See docs/architecture/LEARNING_LLM_ROUTER.md

Phase 4: Zero-Trust Federation Identity ✅ Complete

DID (Decentralized Identifiers) for cryptographic identity — reachable via POST /api/federation/dids
Verifiable Credentials (VCs) for signed claims — reachable via POST /api/federation/credentials
Zero-trust security framework with per-request verification — reachable via POST /api/federation/verify
Automatic credential rotation (90-day)
Note: identity/federation state is in-memory (resets on restart); DB persistence is a documented follow-up

Phase 5: Enhanced Orchestration Patterns ✅ Complete

Conductor Agent (5 execution strategies: SEQUENTIAL, PARALLEL, HYBRID, ADAPTIVE, ROLLBACK_SAFE) — wired into the live workflow engine; reachable via POST /api/v1/workflows/conductor/execute
Workflow State Machine (validated transitions with rollback)
Event Bus (pub/sub event-driven triggering) — every live workflow publishes lifecycle events (WORKFLOW_STARTED/STEP_STARTED/STEP_COMPLETED/STEP_FAILED/WORKFLOW_COMPLETED)
Workflow Templates & Composition (9 primitives: SEQUENCE, PARALLEL, CHOICE, MERGE, SPLIT, JOIN, LOOP, TRY_CATCH, COMPENSATE)

Performance: 27,000+ tests across unit, integration, E2E, and regression suites; comprehensive validation metrics documented

Enhancement Plan → | Validation Metrics →

Installation Options

🐳 Docker (5 minutes)

git clone https://github.com/rush86999/atom.git
cd atom
cp .env.personal .env
# Edit .env — generate the 3 required keys (openssl rand -base64 32):
#   SECRET_KEY, JWT_SECRET_KEY, BYOK_ENCRYPTION_KEY
# ...and set one LLM provider key (or ATOM_LOCAL_ONLY=true for Ollama)
docker compose -f docker-compose-personal.yml up -d --build

Frontend: http://localhost:3001 · Backend: http://localhost:8001 · Swagger: http://localhost:8001/docs

docker-compose-personal.yml is the single-user SQLite stack (no Postgres/Redis). For the full production stack (Postgres + Redis + piece-engine + browser), use docker-compose.yml. See Environment Variables Reference for every variable.

🚀 DigitalOcean (1-Click Deploy)

Launch Atom on DigitalOcean App Platform with one click:

See Cloud Deployment Guide →

💻 Native (10 minutes)

git clone https://github.com/rush86999/atom.git
cd atom

# Backend
cd backend && python3.11 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # edit: SECRET_KEY + one LLM key (or ATOM_LOCAL_ONLY=true)
cd ..

# Frontend
cd frontend-nextjs && npm install --legacy-peer-deps
echo 'NEXT_PUBLIC_API_URL=http://localhost:8001' > .env.local
cd ..

# Start backend (from repo root): PYTHONPATH=$PWD:$PWD/backend \
#   ./backend/venv/bin/python -m uvicorn main_api_app:app --reload --port 8001
# Start frontend: cd frontend-nextjs && npm run dev -- -p 3001

See Quick Start above for the verified commands, or Environment Variables Reference.

Marketplace (Commercial Service)

Commercial marketplace for agents, domains, components, and skills at atomagentos.com. Requires API token connection. Core platform is AGPL v3 (open source), marketplace items are proprietary. See LICENSE.md for terms.

Setup: Add ATOM_SAAS_API_TOKEN to .env and restart. Marketplace Documentation →

Example Use Cases

Department	Scenario
Sales	New lead in HubSpot → Research → Score → Notify Slack
Finance	PDF invoice in Gmail → Extract → Match QuickBooks → Flag discrepancies
Support	Zendesk ticket → Analyze sentiment → Route urgent → Draft response
HR	New employee in BambooHR → Provision → Invite → Schedule orientation

Security & Privacy

Self-hosted deployment, BYOK (OpenAI/Anthropic/Gemini/DeepSeek/MiniMax), encrypted storage (Fernet), audit logs, human-in-the-loop approvals, package security scanning, supply chain protection, 5-phase execution sandbox layer (filesystem scope, tool whitelist, tripwires, Firecracker microVM isolation, dual-proxy egress, resource caps, KillRun, provenance tagging, LLM ActionJudge — Rounds 43-47), comprehensive testing (27,000+ tests across unit, integration, E2E, and regression suites), AI-enhanced bug discovery, and stress testing

Security Documentation → | Sandbox Layer → | Testing Guide →

Documentation

User Guides ⭐

User Guide Index - Complete user documentation (START HERE)
Quick Start Guide - Get started in 15 minutes
User Guide - Core features and daily workflows

Core Features

Agent System - Multi-agent governance and orchestration
Community Skills Guide - 5,000+ skills with Python & npm packages
Office Automation & Co-Editing - Real-time Excel/Word/PPTX co-editing on Canvas ✨ NEW
Python Package Support - NumPy, Pandas, 350K+ packages
npm Package Support - Lodash, Express, 2M+ packages
Episodic Memory - Agent learning system
Agent Graduation - Promotion framework
Student Training - Maturity routing

Testing & Quality ✨ NEW

Quality Assurance Guide - Comprehensive QA practices and standards
Quality Metrics Dashboard - Live quality metrics and trends
Bug Fix Process - TDD-based bug fixing workflow
Coverage Report Guide - Coverage measurement and improvement
E2E Testing Guide - 91+ comprehensive end-to-end tests
Bug Discovery Infrastructure - AI-enhanced bug discovery
Test Quality Standards - Testing best practices
Cross-Platform Testing - Mobile/desktop testing

Platform

Development Guide - Technical setup
Installation Guide - Complete instructions
Environment Variables - Every env var, defaults, and where to set them
Atom vs OpenClaw - Feature comparison

Advanced

Canvas Reference - Canvas operations
Agent Governance - Maturity levels and permissions
Meta-Agent Routing - Intent classification and fleet recruitment
Swarm Coordination - Multi-agent patterns: Field Guide, Branch Reconciler, Megafile Tripwire ✨ NEW
Personal Edition - Local deployment

Complete Documentation Index → | Reorganization Plan →

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quality Standards

All contributions must meet quality standards:

Tests pass (100% pass rate) - All tests must pass before merge
Coverage adequate (≥70%) - New code must have test coverage
Code reviewed - At least one approval required
Documentation updated - Update docs for new features

See Quality Assurance Guide for details.

Support

Documentation: docs/INDEX.md - Complete index
Developer Guide: docs/development/overview.md - Setup
User Guide Index: docs/USER_GUIDE_INDEX.md - User documentation
Blog: Substack - Latest updates & insights
Issues: GitHub Issues
License: AGPL v3 - LICENSE.md

Built with FastAPI | SQLAlchemy | LangChain | Playwright | Next.js

Experience the future of self-hosted AI automation.

⭐ Star us on GitHub — it helps!

atom