AgentOS

The runtime for AI agents that operate computers.

AgentOS is a general-purpose, embeddable agent execution platform that provides the runtime layer for AI agents capable of operating computers. It decouples the core agent reasoning loop, tool execution, permissions, state, and observability from any specific application domain.

---

🚦 Subsystem Implementation Status

To ensure complete architectural honesty (per audit_0.2.md guidelines), every subsystem's operational readiness is categorized below:

Subsystem	Status	Details
ReAct Agent Loop	Implemented	Autonomous observe → reason → act → verify loop with iteration boundaries
Model Abstraction	Implemented	OpenAIProvider, MockModelProvider, multi-tool schema definitions
Permission Engine	Implemented	Deny-by-default filesystem security, path canonicalization (isPathInside), AST command parser (parseCommand), exact-origin matching, SSRF protection
Human Approval	Implemented	Risk-level gating (LOW, MEDIUM, HIGH, CRITICAL), interactive console & custom UI handlers with AbortSignal
Secret Redaction	Implemented	Automatic redaction of sensitive headers, API keys, passwords, and tokens before event emission, approval UI, traces, and SQLite storage
Per-Run Lifecycle & State Machine	Implemented	RunStateMachine, per-run RunContext with real AbortSignal cancellation, typed task.cancelled events, and concurrent run isolation
Event Bus	Implemented	High-throughput typed EventBus with wildcard matching and traceable events (runId, taskId)
Durable Tiered Memory	Implemented	SQLite-backed per-run working, long-term, and cross-run isolated lexical keyword-scored memory retrieval (vector embeddings planned)
SQLite Persistence	Implemented	WAL-mode SQLite storage for runs, events, state, tool_calls, and memory_entries with fail-fast persistenceMode: "required"
Observability & Tracing	Implemented	Structured latency spans, token metrics, sanitized trace records, and exportable JSON execution traces
Workspace Runtime Jailing	Implemented	LocalWorkspace and InMemoryWorkspace enforcing symlink/junction-safe canonical realpath traversal prevention
HTTP / API Tool	Implemented	http_request with Zod validation, cancellation support, manual redirect hop validation, and SSRF DNS pre-resolution defense
Real Browser Automation	AgentOS Native	PlaywrightBrowserProvider driving real Chrome/Edge engines with in-flight AbortSignal cancellation
Code Interpreter Execution	AgentOS Native	Subprocess execution running Python/Node/Shell with host environment sanitization and approval gating
OpenHands Compatibility Adapter	Compatible Adapter	OpenHandsWorkspaceAdapter and OpenHandsEventMapper translating actions & observations with realpath safety
Audit Timeline Reconstruction	Implemented	agent.reconstructTimeline(runId) reconstructing runs, events, and tool logs from SQLite
Deterministic Simulation Re-Execution	Experimental	Re-running reasoning loop against recorded mock responses
OS-Level Container Sandboxing	Planned	Docker / Firecracker microVM execution for untrusted host commands
Control Plane Scheduler & Queue	Planned	Persistent recurring cron jobs and background worker task queue
Desktop GUI Application	Planned	Desktop shell placeholder under agentos/apps/desktop (planned for v0.2)

---

🏛️ Architecture & Philosophy

                         AGENTOS
                            │
             ┌──────────────┴──────────────┐
             │                             │
       Agent Runtime                 Control Plane
             │                             │
      ┌──────┼────────┐             ┌──────┼──────┐
      │      │        │             │      │      │
   Planner Memory   Context      Policy  Events  State
      │
      ▼
    Tools
      │
 ┌────┼─────────────┬─────────────┐
 ▼    ▼             ▼             ▼
Web  Files       Terminal      Interpreter / Upstream
 │
 ├── Playwright Real Browser (AgentOS Native Engine)
 ├── VirtualBrowserSession (Fast Unit Tests)
 ├── Open Browser Use Inspired Launch Policies
 └── Browser Use Inspired Action Schemas

• 🧠 Brain: LLM Provider abstraction, ReAct task decomposition, SQLite durable memory (lexical keyword retrieval), and prompt context injection.
• ✋ Hands: Node.js & workspace filesystem tools, hardened terminal execution, HTTP request tools, real Playwright browser automation, and multi-language code execution.
• ⚡ Nervous System: Strongly typed EventBus, capability-based PermissionEngine (deny-by-default, SSRF defense, secret redaction), Human-in-the-Loop ApprovalManager, SQLite persistence, and structured Tracer.

---

🚀 Quickstart

Installation & Build

# Clone the repository
git clone https://github.com/Fadhlijeu/AgentOS.git
cd AgentOS

# Install dependencies across all workspace packages
pnpm install

# Build all packages to dist/
pnpm build

Real Browser Agent Example

import {
  Agent,
  OpenAIProvider,
  browserTools,
  PlaywrightBrowserProvider,
  ConsoleApprovalHandler,
} from "@agentos/sdk";

// Initialize real Playwright browser provider (uses local Chrome or Edge)
const browserProvider = new PlaywrightBrowserProvider({
  headless: true,
});

const agent = new Agent({
  model: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }),
  tools: browserTools({ provider: browserProvider }),
  permissions: {
    browser: {
      allowOrigins: ["https://example.com", "https://news.ycombinator.com"],
      denyOrigins: ["https://untrusted-site.com"],
    },
    approval: {
      requireFor: "HIGH",
    },
  },
  approvalHandler: new ConsoleApprovalHandler(),
});

const result = await agent.run(
  "Navigate to https://example.com, inspect the page, and report the headline."
);

console.log("Agent result:\n", result.output);
await agent.dispose();

---

📦 Packages in Monorepo

Package	Purpose
@agentos/sdk	Unified client entry point bundling all runtime, tooling, and adapter modules
@agentos/agent	Main agent runtime and AgentRuntime orchestrator coordinating multi-run lifecycles
@agentos/core	Shared types, enums, ModelProvider, WorkspaceAdapter, BrowserSession
@agentos/events	Strongly typed event bus, wildcard handlers, and traceable event stream
@agentos/tools	Tool contracts, ToolRegistry, filesystem tools, terminal tools, HTTP, and browser tools
@agentos/permissions	Path jailing (isPathInside), safe command parser (parseCommand), origin policies
@agentos/planner	ReAct reasoning planner with system prompt task decomposition
@agentos/memory	Durable SQLite memory manager with tiered retrieval (working, long-term, semantic)
@agentos/storage	SQLite persistence using better-sqlite3 with WAL mode, indexing, and audit tables
@agentos/observability	Structured tracing, execution latency metrics, and JSON trace export
@agentos/runtime	RunStateMachine, isolated RunContext with AbortSignal, AgentRun handles
@agentos/adapters	Real PlaywrightBrowserProvider, OpenInterpreterAdapter, OpenHandsWorkspaceAdapter
@agentos/playground	Interactive CLI application to explore and verify agent capabilities

---

🧪 Verification & Testing

# Run complete test suite (all unit, security, concurrency, memory, workspace tests)
pnpm test

# Run real browser integration test
pnpm run test:real-browser

# Run offline ReAct filesystem demo
pnpm example:filesystem

# Check entire repository TypeScript types
pnpm run typecheck

---

📚 Third-Party Provenance & Upstream Inspiration

AgentOS implements native TypeScript execution capabilities inspired by and protocol-compatible with the following open-source projects:

• OpenHands Software Agent SDK (22c85eb0e0db8f4386380d095e9fe6933af2e65f) — MIT: Workspace abstraction and action/observation event mapping protocol.
• Browser Use (d8110c5ff87ccba887aaa726cdb780f2f84bef8d) — MIT: Perception-action browser loop schemas and DOM interactive element extraction.
• Open Browser Use (7765002ac88040aedc781be89afe68475a9d6c88) — MIT: Stealth launch policies, locator conventions, and session management paradigms.
• Open Interpreter (5db50b2e93224dda720462f02fc2858cbd112eb5) — Apache-2.0: Multi-language code execution patterns and output streaming.

Full provenance records, exact commit SHAs, license terms, and layer ownership boundaries are documented in THIRD_PARTY.md and integrations/.

---

📄 License

MIT © 2026 Fadhli