An operating system for AI agents is an application runtime that manages work around agents: execution, retained state, memory, permissions, and coordination. The useful promise is that those responsibilities have explicit owners instead of being scattered across terminal sessions and scripts. The name alone does not establish which responsibilities a product implements.
For CompozyOS, the phrase describes a local daemon that runs ACP-compatible agent integrations and connects their sessions to Loops, automation, memory, and operator controls. It runs on your existing host operating system. It does not replace that OS or make every model call local.
This article explains our architecture and its limits, checked against the implementation on September 11, 2026. It also separates that product meaning from the research use of “agent OS.”
The research meaning and the product meaning
The paper AIOS: LLM Agent Operating System, by Kai Mei and coauthors, proposes separating shared services such as scheduling, context, memory, storage, and access control from agent applications into an AIOS kernel. Its focus is resource management for LLM-based agents.
That is useful background for the category, but CompozyOS is not an implementation of that paper's kernel, and the paper's evaluations do not establish CompozyOS performance.
A related term is agent harness. Birgitta Boeckeler's harness engineering essay discusses the machinery and practices around a coding model, including what ships inside an agent and what its users add around it. That framing helps locate the boundary: an agent integration already has a harness, while a surrounding runtime may manage several such integrations and their work over time.
You do not need to settle the category name before evaluating a product. Ask which durable objects it owns, which operations it exposes, and what happens when execution fails.
Start with a session, not a window
In CompozyOS, a session is a durable logical unit of work. It associates an agent definition, workspace, permission policy, event history, and stable ID. Creating a session does not immediately start a provider process. The first prompt binds the provider runtime.
That separation answers a practical question: if you close the interface, where is the work? The daemon owns the record. CLI, Web, and desktop views inspect it through the runtime rather than each inventing their own conversation store.
operator: CLI / Web / desktop
|
v
CompozyOS daemon
sessions, tasks, Loops, automation
event history, memory, permissions
|
ACP connection
|
v
selected agent integration
|
configured model serviceThis is a logical architecture diagram. It shows ownership and communication, not separate machines. The provider and model service determine where inference takes place.
The durable record also has limits. A machine reboot ends its subprocesses. Some stopped sessions can restore through a normal prompt, while terminal failures remain historical records requiring a new session. Session lifecycle explains those cases. Durability preserves state; it is not a promise of uninterrupted execution.
Give each kind of state its own meaning
Several objects can contain text or timestamps without being interchangeable:
| Object | Question it answers |
|---|---|
| Session history | What happened during this conversation and execution? |
| Task run | Which attempt performed a unit of assigned work? |
| Loop definition and run | What control flow was requested, and where did it reach? |
| Memory | What reusable knowledge should a later turn recall? |
| Approval record | Which action or boundary received a decision? |
| Automation job and run | What should start on a schedule, and what was dispatched? |
For example, the fact that an agent once ran a command is history. It does not by itself create a standing permission to run that command again. A remembered project convention can help a model reason, but cannot grant access. A scheduled job can request work, but its run history must still show whether execution happened.
CompozyOS keeps live session events in events.db and materializes a forensic JSONL ledger after
stop. The memory recall pipeline does not ingest that ledger as a memory scope. That boundary
helps keep “what happened” separate from “what should be recalled.” See
sessions and memory.
Continuous work needs explicit failure behavior
Loops and automation make repeated work part of the runtime. A Loop carries control flow and run state; an automation job supplies a schedule and target. Neither should be judged only by whether a demo can start a run.
Ask what happens if the previous run is unfinished, the machine misses a scheduled instant, or a tool fails after an external effect. CompozyOS's job scheduling documents catch-up policies, overlap handling, and retries. Its Loop failure handling documents node and run behavior.
The runtime can make these decisions inspectable. It cannot infer that repeating an arbitrary external operation is safe. A workflow that publishes a report still needs to connect the approved report version to the actual publication result.
Permissions are enforcement points, not personality
An agent definition can select deny-all, approve-reads, or approve-all. The daemon applies
policy to the relevant execution surfaces and records interactive decisions when applicable.
An optional SOUL.md supplies persona; it cannot configure providers or grant tools.
Those controls should be evaluated alongside the execution environment. A local provider runs on the host, and a Git worktree separates files without containing arbitrary process behavior. The permissions and safe-spawn guide explains how policy, child lifetime, and task reviews work together without becoming a blanket sandbox claim.
The same care applies to remote access. The gateway requires explicit exposure configuration, and reachability is separate from device authentication and signed delivery. CompozyOS does not buffer inbound webhook deliveries while the daemon is offline. Sender retries and an appropriate hosting plan remain operational responsibilities.
Try the boundary on your own machine
On a supported macOS or Linux machine, follow the installation guide. For a fresh CLI setup:
curl -fsSL https://compozy.com/install.sh | sh
compozy install
compozy daemon start
compozy config validateConfigure and authenticate the provider you intend to run. Then, from a repository:
compozy session new --cwd "$PWD" --agent general --name first-inspection
compozy session list -o jsonThe expected initial state is an active session with an unbound runtime. Replace sess_1234
with the returned ID to bind the provider and inspect the result:
compozy session prompt sess_1234 \
"Explain this repository's structure and cite its entry files."
compozy session history sess_1234
compozy session recap sess_1234These commands expose the distinction directly: creation allocates the record, a prompt performs work, and history reads what remains. They require a working provider; a successful record creation alone does not prove model execution.
CompozyOS is MIT-licensed and remains in beta. The local runtime does not remove model-provider costs, host operation, or the need to validate a workflow's output.
Evaluate the system by what you can inspect
An agent OS is useful when it gives you a consistent place to answer operational questions: which agent ran, what it could access, what state it kept, what started the next attempt, and what still needs a decision. A desktop interface can make those answers easier to find, but the underlying records and enforcement points are what make them dependable.
Start with one session and follow its state through creation, execution, and inspection. Then add a bounded child or scheduled job. That progression gives the category a concrete meaning in your workflow instead of asking you to accept an “OS” label on its own.