AgentOS: Guide to the Lightweight OS Kernel That Runs LLMs as Independent Processes

Core Concept: AgentOS is a proof-of-concept operating system kernel written in Go. It treats Large Language Models (LLMs) as independent long-running processes, interacts with the environment via strict JSON system calls, and implements an agent architecture similar to traditional OS process management.

Original Author and Source:

• Maintainer: pipelinelord
• Source: GitHub (Link)
• Release Time: 2026-06-12

Core Architecture Overview: Drawing on traditional OS architecture, it replaces CPU threads with LLM context windows. Core components include the process manager, scheduler, system call dispatcher, and hardware driver layer.

Background: Why Do We Need AgentOS?

Most current LLMs use a request-response mode (user sends a prompt → model returns text → conversation ends). This mode is simple and straightforward, but it's difficult to support continuous operation and continuous interaction with the environment in agent scenarios:

• For example: Long-term monitoring of file system changes, periodic network information queries, collaboration with other AI processes to complete tasks, etc.

AgentOS is designed precisely to address the needs of these scenarios.

Core Architecture and Execution Loop Analysis

Core Architecture Components

• Process Manager: Maintains the Agent Process Control Block (AgentPCB), recording information such as PID, status, and memory pointers.
• Scheduler: Background loop that evaluates process status and triggers LLM inference (when the process is running).
• System Call Dispatcher: Parses JSON commands generated by LLMs and routes them to corresponding hardware drivers.
• Hardware Driver Layer: Encapsulates host system interfaces (Docker, file system, network, vector database, etc.).

Execution Loop Steps

1. Context Construction: Collects system instructions, role definitions, and historical records (communication messages, events, system call results).
2. LLM Inference: Sends prompts to LLMs (e.g., Gemini 1.5 Flash) to generate responses containing [SYS_CALL::...] JSON blocks.
3. Distribution Phase: Parses JSON; if invalid, injects error information into the context; if valid, routes to the processor.
4. Execution Phase: The processor interacts with drivers/internal components to complete hardware operations.
5. Status Update: Injects execution results into the context and restarts the loop.

This design transforms LLMs from one-time tools into continuously running "processes".

System Calls: Detailed Explanation of the Agent's "Instruction Set"

AgentOS provides multiple types of system call interfaces:

• Execution Lifecycle:
  • SPAWN_AGENT: Spawns child processes (supports permission restrictions and output routing);
  • EXEC_CMD: Executes bash/powershell commands;
  • SYS_EXIT: Terminates the agent.
• File System: Sandboxed (restricted to /workspace/ directory), FS_READ/FS_WRITE for file reading/writing (prevents path traversal).
• Network: Only supports NET_FETCH (HTTP GET requests, response ≤5MB, timeout mechanism).
• Memory: Implemented via ChromaDB, MEM_WRITE for embedding storage of knowledge, MEM_READ for semantic retrieval (long-term memory).
• IPC: SEND_MSG/RECV_MSG for asynchronous peer-to-peer communication; SYS_WRITE_STDOUT/SYS_READ_STDIN for standard IO; the pipe_to parameter can route output to the target process.
• Others: Timers (SLEEP/SYS_SCHEDULE), Webhook support (responds to external events).

Security Protection: Multi-Layer Isolation and Error Recovery

AgentOS's security mechanisms include:

1. RBAC Permission Control: Child agents are created with the least privilege principle, restricting disk/network access.
2. File System Isolation: Automatically strips path traversal symbols (e.g., ../), and operations are locked to the sandbox directory.
3. Network Restrictions: Only allows GET requests to prevent modifying external system states.
4. Structured Error Recovery: When LLMs generate invalid JSON, decoding errors are captured and friendly prompts are injected, allowing LLMs to self-correct in the next cycle.

These mechanisms grant AI capabilities while maintaining behavioral controllability.

CLI Tools: Operation and Management of AgentOS

AgentOS is compiled into aos.exe via the Cobra framework, providing the following commands:

• aos spawn: Starts the OS and bootstraps the root process (can specify model/role prompts);
• aos ps: Lists all active processes and their PIDs;
• aos top: Displays real-time telemetry (token consumption, number of system calls);
• aos logs [PID]: Streams the thought process and output of a specific agent;
• aos kill [PID]: Forcibly terminates an agent.

These commands simplify the daily management of AgentOS.

Technical Significance and Future Development Directions

Technical Significance

AgentOS represents a paradigm shift in LLM applications: it elevates LLMs from API endpoints to "computing units" (similar to traditional OS processes), supporting continuous operation and interaction.

Potential Application Scenarios

• Long-term monitoring agents;
• Complex task automation (multi-step collaboration);
• Personal assistants with memory;
• Agent collaboration networks.

Current Limitations and Future

Currently in the proof-of-concept stage: network only supports GET, file system is strictly sandboxed, and LLM providers are limited. More features can be expanded in the future, but controllability must be maintained.

Developer Value

Provides a reference implementation for exploring agent architectures. The Go code is concise and clear, drawing on traditional OS design and optimized for LLMs.