Kronos Agent OS: a self-hosted runtime for durable AI agents

An agent that answers one prompt is easy to demo. An agent that runs for weeks has a different failure surface: interrupted turns, stale tools, unreviewed skills, unclear permissions, memory you cannot inspect, and side effects that may run twice after a restart.

Kronos Agent OS is my attempt to make that operational layer explicit. KAOS is a self-hosted Python runtime around an LLM. It owns the parts that survive a conversation: state, memory, skills, tools, scheduled work, policy, audit records, and optional coordination between agents.

This article replaces the original launch comparison with a source-backed review of the current code. The important question is no longer whether KAOS has a longer feature list than another project. It is which guarantees the runtime implements, which ones it tests, and where the alpha label still matters.

Current status: GitHub and PyPI are not on the same version

As of this update, the repository is tagged v0.3.0 and the package metadata in main also reports 0.3.0. PyPI still serves 0.1.1. That mismatch matters because several capabilities described below arrived after 0.1.1.

For the current source release, pin the Git tag:

git clone https://github.com/spyrae/kronos-agent-os.git
cd kronos-agent-os
git checkout v0.3.0

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

kaos demo
kaos doctor

kaos demo is deterministic and runs without an LLM key, Telegram, or Docker. It proves that the CLI, workspace, policy defaults, and core runtime can start. It does not prove that a configured model, MCP server, browser, or sandbox works; those have separate checks.

The project remains alpha software. MIT licensing makes the code available to inspect and modify; it does not turn a local agent into a safe unattended production operator by itself.

The runtime boundary

KAOS accepts work from the CLI, Telegram, Discord, webhooks, and scheduled jobs. Those entry points converge on one runtime pipeline:

CLI / messenger / webhook / scheduler
                  |
                  v
          KronosAgent runtime
          |       |        |
       memory   tool gate   durable journal
          |       |        |
       skills   MCP/tools   effects ledger
                  |
          dashboard + audit

The core loop is a readable asynchronous ReAct engine built on LangChain message and tool types. It controls turn limits, tool execution, callbacks, and termination without requiring LangGraph for the main runtime. LangGraph is still an optional dependency for the ASO subsystem, so “no LangGraph” describes the core loop, not the entire repository.

That distinction is typical of the project: features are separated by responsibility instead of being hidden behind the Agent OS label. The model chooses actions. The runtime validates policy, records state, calls tools, persists results, and decides whether an interrupted action can be resumed.

Durable turns need an effects ledger

Persisting chat history is not enough to make an agent durable. If a process crashes after sending a message but before marking the turn complete, replaying the turn can send the same message again.

KAOS v0.3.0 journals active turns and records external effects with optional idempotency keys. Resume logic can distinguish a new action from an effect that already happened. A retry ceiling stops a broken turn from entering a permanent crash loop.

Longer work uses plans. A plan contains a goal, dependency-aware steps, and explicit wait conditions: time, a user response, manual resume, a page condition, or a numeric threshold. Each ready step runs as a normal governed agent turn, so approvals, budgets, durable execution, and audit rules are reused rather than reimplemented in the planner.

This is one of the useful boundaries between an agent framework and an operating layer. The planner does not receive a secret bypass around the runtime just because it runs later.

Memory is layered, but not mandatory

KAOS can combine several stores:

• SQLite session history for recent turns;
• FTS5 facts for exact keyword recall;
• optional Mem0 vectors for semantic recall;
• a knowledge graph for entities and relations;
• shared facts for optional multi-agent deployments;
• sleep-time consolidation for deduplication and graph extraction.

The vector layer is an optional installation extra. A basic runtime should not require a local embedding stack merely to start. This also keeps the architecture testable: exact recall, semantic recall, and graph traversal are different operations and can fail independently.

The larger design lesson is covered in the agent memory guide: retrieval quality depends on provenance, retention, conflict handling, and deletion, not on the number of storage engines in a diagram. KAOS exposes memory and sessions through the control room so an operator can inspect and remove state instead of treating memory as an invisible prompt appendage.

Tools and skills are supply-chain inputs

MCP makes tool discovery convenient, but a server that silently stops exposing tools can leave an agent producing plausible answers from weaker sources.

That happened in a real KAOS deployment. Resilient startup brought the agents online with 102 tools instead of 113; two MCP servers had been broken for months without making the process fail. Version 0.3.0 added kaos mcp check and a daily smoke job that starts every known server, calls tool discovery, reports the count, and treats “started with zero tools” as broken. Failure text is redacted before it reaches the report.

The sandbox had a similar false-green check. Docker and the image existed, so readiness passed, while the container could not read its temporary directory on one path and interpreted a relative bind mount incorrectly on another. kaos sandbox check now executes code and verifies containment properties from inside the container. If execution fails, KAOS does not fall back to running dynamic code unsandboxed.

Skills receive the same skeptical treatment. The registry can verify a content checksum, an SSH signature from a configured key, a compatible KAOS version, and an offline scenario. A skill becomes active automatically only when its configured trust policy and check pass. Otherwise it lands as a draft with a reason.

These checks are more valuable than a claim that the runtime “supports MCP” or “has a sandbox.” They test the capability an agent actually needs. The related threat model is described in the MCP security guide.

Governance is data, not scattered flags

A policy.yaml file can define capabilities, approvals, budgets, egress, retention, PII masking, and how untrusted content is handled. kaos policy report prints the effective value and its source. Environment variables override policy, and policy overrides defaults. An invalid policy stops startup rather than silently returning to permissive behavior.

The public defaults keep high-risk surfaces off:

ENABLE_DYNAMIC_TOOLS=false
REQUIRE_DYNAMIC_TOOL_SANDBOX=true
ENABLE_MCP_GATEWAY_MANAGEMENT=false
ENABLE_DYNAMIC_MCP_SERVERS=false
ENABLE_SERVER_OPS=false

Telegram also defaults to an allowlist posture. Dynamic code requires the sandbox. Browser navigation and skill imports can use an egress allowlist. External MCP output, public messages, documents, and browser content are marked untrusted before they enter the model context.

Tool and security audit logs are hash-chained. kaos audit verify can identify the first edited, removed, or reordered entry. This makes tampering visible; it does not make the log immutable. Anyone with file access can still replace the whole directory, so a serious deployment should ship logs to storage outside the agent’s account.

Agent behavior needs replay, not a prose promise

Unit tests can prove that a policy parser works. They do not show whether a prompt change altered tool order or removed an approval gate.

KAOS Agent CI uses two mechanisms:

• cassettes replay provider and untrusted tool calls for identical inputs;
• scenarios replay the observed sequence of model turns and assert tool paths, call limits, approval requirements, forbidden tools, and selected output properties.

kaos eval diff --base origin/main runs the base revision in a temporary worktree and reports structural behavior changes. The suite runs without provider keys. It deliberately does not claim to measure answer quality after a prompt change: the scripted model pins the deterministic half of the run. Semantic quality still needs live evals with representative tasks and human review.

This separation is honest and useful. An offline scenario can catch “write tool no longer asks for approval.” It cannot tell you whether a new system prompt gives better travel advice.

Portable state with explicit refusals

A .kaos bundle can export persona files, skills, facts, graph data, shared facts, and pending schedule entries. A manifest contains a SHA-256 for each artifact, and import verifies the full payload before writing.

The exporter deliberately leaves out .env files, Telegram sessions, raw SQLite databases, vector stores, and audit logs. Imported skills arrive as drafts. Foreign session history goes to an inbox note instead of overwriting live threads. A dry run follows the same merge path without committing changes.

Importers currently handle ChatGPT exports, Claude projects, Obsidian vaults, selected Telegram chats, and Letta agent files. The useful property is not the list. It is that every importer converts into one verified bundle format and uses the same merge rules.

Swarm Mode is optional

The default KAOS runtime is one durable agent. Swarm Mode adds separate agent processes with their own persona, workspace, memory, and optional messenger account. A shared SQLite ledger coordinates implicit replies with IMMEDIATE transactions.

Version 0.3.0 moves more of the organization into agents.yaml: ownership, escalation targets, SLA minutes, per-agent budgets, required dissent review, and reply caps. Agents can still make probabilistic relevance decisions, but duplicate-send arbitration and budget enforcement remain deterministic.

Use this only when independent roles improve the task. For most workflows, one agent with explicit tools and a review step is easier to operate than a panel. The trade-offs are covered in the multi-agent architecture guide.

Where KAOS fits

KAOS is a reasonable fit when you want:

• a self-hosted Python runtime rather than a managed agent service;
• inspectable memory, jobs, tool calls, policies, and durable turns;
• scheduled work that uses the same approvals and budgets as chat;
• MCP and custom tools behind conservative capability gates;
• portable agent state and deterministic behavior checks;
• optional multi-agent coordination without making it the default.

It is a poor fit when you only need a stateless API call, a turnkey consumer assistant, or a mature platform with long-term compatibility guarantees. The project is young, its GitHub and PyPI releases currently differ, and enabling browser, server, or dynamic-code capabilities creates an operations burden you must own.

The practical claim is narrower than the original article: KAOS does not make agents autonomous or safe by declaration. It makes their state, permissions, effects, and failures more visible and testable. For a long-running agent, that is the work that starts after the demo succeeds.

Sources

• Kronos Agent OS repository and v0.3.0 documentation
• KAOS changelog
• KAOS security model
• KAOS Agent CI
• kronos-agent-os on PyPI