Project: AgentOS POC
What if an LLM wasn't a chatbot but a CPU? AgentOS is a Go-based runtime that manages AI agents as long-running processes, with real syscalls, sandboxing, scheduling, and inter-agent communication.

Advertisements
The Problem - AI today is a vending machine
Every time you call an LLM API Gemini, Claude, GPT the pattern is the same. You send a message. You get a response. The model forgets you exist. Even in multi-turn chat, the model has no real persistence. It doesn't act on its own. It doesn't run in the background. It doesn't coordinate with other agents. It waits for you.
That's fine for a chatbot. It's completely insufficient for anything autonomous.
I wanted to build something where an AI agent could run continuously without human prompting, take real actions, read files, run commands, fetch URLs, remember what it has done across many cycles, spawn child agents to delegate work, and sleep and wake on a schedule. Nothing like this existed as a lightweight, self-hostable, open system. So I built it.

Treat the LLM like a CPU
Every design decision in AgentOS flows from one analogy. In a traditional OS, the CPU executes instructions in a loop: read state, perform an operation, write results, repeat. The OS manages which programs get CPU time, how they access hardware, and how they communicate with each other.
AgentOS replaces the CPU with an LLM. Instead of executing machine instructions, the "CPU" reads a context window, generates a decision, and outputs a structured command. The OS executes that command against real hardware and feeds the result back into the context.

💡 Important nuance
AgentOS is not a real kernel. It does not have privileged hardware access. It borrows the host OS kernel for all real I/O via normal Go standard library calls. The word "kernel" describes the architecture pattern not a technical claim about hardware ring levels.
Architecture - Four subsystems, one Go binary
AgentOS is a single compiled Go binary — aos — containing four major subsystems working together inside a Docker container.

Process Model - Inside the Agent PCB
Every running agent has a Process Control Block, the OS's complete record of that agent. The host machine has no idea individual agents exist. From the host's perspective there is exactly one process: the aos binary. AgentOS PIDs are its own internal numbering.

🔑 Why Context History is the critical field
The LLM has no memory between API calls. The history is rebuilt into a prompt on every single tick. The agent "remembers" only because it re-reads its own notebook at the start of each cycle. Stateless component — stateful system.
The tick cycle: the heartbeat of the system
The scheduler runs as a background goroutine from boot. It loops continuously through every agent in the process table and drives the entire system forward. This is not a busy loop between steps the goroutine blocks on network calls, consuming no CPU.

⚡ Why this isn't resource-wasteful
Between ticks the agent goroutine is blocked waiting on the LLM API a network call. The goroutine sleeps. Zero CPU is consumed. Actual LLM inference runs on the provider's servers. AgentOS is the lightweight coordinator, not the compute engine.
The contract between agent and OS
A syscall is the only mechanism an agent has to interact with the outside world. The LLM cannot directly read files, run commands, or send messages. It must ask — through a structured text format and the OS decides whether to allow it, then executes it.
# The format every syscall must follow
[SYS_CALL::SYSCALL_NAME] {"key": "value"}
# Examples
[SYS_CALL::FS_READ] {"path": "/notes.txt"}
[SYS_CALL::NET_FETCH] {"url": "https://api.example.com/data"}
[SYS_CALL::SEND_MSG] {"to_pid": 2, "content": "task complete"}
[SYS_CALL::SYS_EXIT] {}
Execution & Lifecycle
SPAWN_AGENT Fork a child agent with its own model, role, and permission set. Enables multi-agent delegation with least-privilege enforcement at spawn time.
EXEC_CMD Run a real bash/shell command via Docker or local OS. The only syscall that creates a real host-level process — runs, returns stdout/stderr, exits.
SYS_EXIT Cleanly terminate the agent. Status becomes TERMINATED. Scheduler stops ticking it. PCB is eventually cleaned up.
File System
FS_READ Read a file. All paths are jailed to /workspace/ — traversal sequences (../) are stripped before execution. Cannot escape the sandbox.
FS_WRITE Write to a file. Same sandbox rules. Agent cannot write to host filesystem regardless of path provided.
Network
NET_FETCH HTTP GET only — no POST/PUT/DELETE. Prevents agents from mutating external state. Response capped at 5MB with timeout enforcement.
Vector Memory
MEM_WRITE Embed and store knowledge in ChromaDB. Text is converted to a vector searchable by meaning, not just exact keywords.
MEM_READ Semantic search. "Payment issues" can return notes about "invoice failures" meaning-based retrieval, not keyword matching.
Inter-Process Communication
SEND_MSG Async point-to-point message to another agent by PID. Lands in target's STDIN buffer. Dequeued on next RECV_MSG call.
RECV_MSG Dequeue the next message from this agent's inbox.
SYS_WRITE_STDOUT Push to STDOUT. If pipe_to was configured at spawn, output injects directly into the target agent's STDIN — Unix-style pipes between agents.
Timers
SLEEP Suspend for N seconds. Status becomes SLEEPING. Scheduler skips it. Zero CPU consumed during sleep.
SYS_SCHEDULE Register a background timer that injects a specific prompt and wakes the agent in N seconds. How you build agents that do scheduled autonomous work.
Webhooks
SYS_REGISTER_WEBHOOK Bind this agent to a URL on the local port 8088 server. External HTTP requests to that path wake the agent and inject the payload.
SYS_WEBHOOK_REPLY Respond to a pending HTTP request with a custom status and body. Agents can act as real HTTP endpoints, receiving and responding to external events.
Defence in depth — four enforced layers
You cannot rely on the LLM to "decide" not to do something harmful. Security in AgentOS is architectural enforced at the infrastructure level before the agent's output ever reaches a driver.

A monitoring agent: tick by tick
A root agent is spawned with the role: "Check our API endpoint every 60 seconds and write a log entry." Here is exactly what happens across three ticks; no human involvement after the initial spawn.

One command on any machine with Docker
AgentOS ships as a Docker image with zero secrets baked in. All API keys, passwords, and storage credentials are injected at runtime via environment variables. The image contains only the binary and dependencies.
⚠️ Golden rule of container distribution
Image = behaviour. Environment = configuration. Never mix them. A published image with a hardcoded API key is a critical security failure. AgentOS enforces this separation by design — the SSH password itself is set at runtime via the entrypoint script.
# Complete deploy on any machine
git clone https://github.com/you/agentos
cd agentos
cp .env.example .env # fill in GEMINI_API_KEY and SSH_PASSWORD
docker compose up -d
ssh root@localhost -p 2222# CLI reference
aos spawn --model "gemini-1.5-flash" --role "You are a research agent"
aos ps # list all agents and their current status
aos top # live telemetry: tokens, syscalls, uptime
aos logs 1 # stream the thought process of PID 1
aos kill 2 # SIGTERM equivalent — forcefully terminate PID 2What I actually learned building this
The context window is the program counter
The LLM's position in a task is entirely determined by what's in its history. Engineering that history — what goes in, in what order, how results are formatted is the real skill of building reliable agents. It's not AI engineering. It's memory management.
Stateless components can build stateful systems
The LLM has no memory. The scheduler has no opinion. But together, with carefully managed state in the PCB, they produce something that behaves like a continuously thinking entity. Emergence through composition the same principle that makes TCP reliable on top of UDP.
Security must be architectural, not procedural
You cannot instruct an LLM to "not do harmful things" and trust that. The sandbox, the RBAC, the GET-only network restriction these are enforced at the infrastructure level. The agent literally cannot escape them regardless of what it outputs. Design the system to make bad outcomes impossible, not just unlikely.
The metaphor is load-bearing
Starting from "what if an LLM were a CPU?" gave every subsequent design decision a clear test: does this fit the model? That clarity of metaphor prevented architectural drift. Good abstractions are productive constraints, not just naming conventions.
The road from POC to platform
This is a proof of concept it demonstrates the thesis but is not production-hardened. The architecture is sound. The natural extensions are clear.

The gap between "AI that answers questions" and "AI that gets things done" is an infrastructure gap. The models are capable enough. What's missing is the operating system layer and that's exactly what AgentOS is.
Author's Note
Chamath P.
DevOps Engineer
DevOps Engineer writing practical guides on Kubernetes, CI/CD, IaC, and SRE — based on real production experience.
This article was written with AI assistance. All technical claims and code examples have been personally verified before publishing.
Advertisements