🛡️ Agent OS

A secure, self-healing, and strictly governed runtime environment for LLM Agents.

🇨🇳 简体中文 (Chinese README)

---

💡 What is Agent OS?

LLM Agents are powerful, but giving them raw access to shell commands, filesystems, and databases invites disaster (e.g., prompt injection leading to file loss, looping code execution causing token overspend).

Agent OS is a lightweight, low-level runtime safety and governance framework that serves as a "Security Moat" between LLM agents and physical operating systems / databases. It intercepts, sanitizes, and cryptographic-governs all agent inputs, system executions, and data writes.

---

⚖️ Why Agent OS?

Security Features	Raw Agent SDK (e.g. LangChain, LlamaIndex)	Agent OS Runtime
Filesystem Safety	❌ None (raw path manipulation allowed)	✅ Strict sandbox directory restrictions (allowed_paths)
Command Execution	❌ Run any command (exec / system)	✅ Rigid whitelist control & shell argument sanitization
Prompt Injection	❌ Vulnerable to prompt jailbreaks	✅ Run-time SemanticFirewall input sanitization
Runaway Breaker	❌ Infinite loops leading to high API bill	✅ BillingFuse spending quotas & CircuitBreaker logic
Database Writes	❌ Raw Cypher/SQL queries execution	✅ Cryptographic WriteGate 3-stage validation + SHACL

---

🔌 MCP Server (Claude Desktop Integration)

Agent OS can run as a Model Context Protocol (MCP) server, providing a "Governance Gateway" for Claude Desktop and other MCP-compatible clients.

3-Line Setup for Claude Desktop

Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "agent-os": {
      "command": "agentos",
      "args": ["start-mcp", "--port", "8100"]
    }
  }
}

That's it! Your Claude Desktop agent is now strictly governed by Agent OS's semantic firewall and write gates.

---

🚀 Quick Start (Local Development)

1. Spin up Safe Storage (Neo4j & Langfuse)

We provide a pre-configured community Docker stack:

docker compose -f docker/docker-compose.yml up -d

2. Install Dependencies

pip install -e ".[dev]"

3. Run the E2E Integration Verification

Test the entire safety cycle (firewall, billing fuse, and database write checks) in one go:

export RYUK_DISABLED=true
python3 -m pytest tests/ -v

4. Execute the Demo Script

Observe the runtime in action:

agentos loop run --task "Run demo"
# or python3 scripts/run_demo.py

---

🛡️ Three-Tier Testing Constitution

We enforce a strict quality gate in our development workflow:

1. L1 Unit Tests: No external dependencies. Run logic check.
2. L2 Integration Tests: Uses testcontainers to launch actual Neo4j instances to check actual transactional batch writes.
3. L3 E2E Tests: Simulates full user flow (e.g. employee onboarding SOP card approvals).

Please read our Contributing Guide for more details.

---

🏗️ Architecture & Control Flow

Agent OS integrates safety hooks directly into the kernel dispatch cycle:

graph TD
    User([Agent Input]) -->|1. Dispatch| Kernel[AgentOSKernel]
    
    subgraph Pre-Dispatch Hooks
        Kernel -->|2. Scan| Firewall[SemanticFirewall]
        Kernel -->|3. Check Breaker| Breaker[CircuitBreaker]
    end
    
    subgraph Governance Moat
        Kernel -->|4. Validate| AutonomyPolicy[AutonomyPolicy]
        Kernel -->|5. Validate SHACL| WriteGate[WriteGate]
        WriteGate -->|6. Check Nonce| NonceCheck{Valid Nonce?}
    end
    
    NonceCheck -->|Yes| Database[(Neo4j Community)]
    NonceCheck -->|No| Block[Block Write & Fail]
    
    subgraph Post-Dispatch Hooks
        Kernel -->|7. Audit Token| Billing[BillingFuse]
    end
    
    Billing -->|Output| Response([Safe Action Output])

---

📄 License

Distributed under the MIT License. See LICENSE for more information.