GitHub - rush86999/atom: Atom Agent, Open-Source AI Agent Platform for Self-Hosted Automation

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

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).

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:

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 →

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 (DATABASE_URL, SECRET_KEY, at least one LLM key)
cp backend/.env.example backend/.env
# Edit backend/.env — generate SECRET_KEY with: openssl rand -base64 48

# 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)

Canvas 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

🚀 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
docker-compose -f docker-compose-personal.yml up -d

🚀 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
cd backend && python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cd ../frontend-nextjs && npm install
cp .env.personal .env
# Start backend: cd backend && python -m uvicorn main_api_app:app --reload
# Start frontend: cd frontend-nextjs && npm run dev

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

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
• Atom vs OpenClaw - Feature comparison

Advanced

• Canvas Reference - Canvas operations
• Agent Governance - Maturity levels and permissions
• Meta-Agent Routing - Intent classification and fleet recruitment
• 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:

1. Tests pass (100% pass rate) - All tests must pass before merge
2. Coverage adequate (≥70%) - New code must have test coverage
3. Code reviewed - At least one approval required
4. 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