# CompozyOS: a daemon-owned runtime for long-running AI agent work

> CompozyOS packages loops, cron, memory, approvals and observability around the agent CLIs you already run. The v0.3 line is beta, the v0.2 product is deprecated, and the install path is a verified shell script or an npm tag.

**compozy/compozy** — Drive the full lifecycle of AI-assisted development, from idea to shipped code.

- Repository: https://github.com/compozy/compozy
- Website: https://compozy.com
- Stars: 2,784 · Forks: 182
- Language: Go
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/compozy-compozy

## The problem CompozyOS targets: agents that stop when the terminal closes

Prompting an agent is easy. Keeping one working is not. The README frames the gap directly: "Anyone can prompt an agent. Making agents work continuously is still an engineering project." The list it gives for that engineering project is loops, triggers, cron, memory, permissions, approvals, observability, and the glue scripts holding them together. CompozyOS is an attempt to make those first-class objects in one runtime rather than a pile of shell wrappers around an agent CLI.

The intended audience is stated plainly: developers and technical operators. That is narrower than it sounds. A developer who runs Claude Code interactively a few times a day does not need a daemon, a workspace-scoped config hierarchy or an extension SDK. Someone who wants a nightly job to pick up tasks, run an agent against a repository, pause for approval before pushing, and leave an inspectable record of what happened is the person this is built for.

The product is also explicitly positioned as the system around the agent, not the agent itself. CompozyOS does not ship its own model or its own coding agent. It drives ACP-compatible CLIs, naming Claude Code, OpenClaw and Hermes. That is a deliberate boundary, and it means the quality of the underlying agent still determines the quality of the output.

## Daemon-owned state: how the runtime actually holds work together

The architecture described in the README is a home-scoped daemon. Clients send commands through public control surfaces; the daemon resolves the workspace, applies permissions and runtime policy, coordinates ACP agents, and persists events and resource state. Web and streaming clients read that same daemon-owned truth rather than keeping a parallel model. The practical consequence is the headline claim: sessions and Loop runs belong to the daemon, so closing a client does not erase the work.

That single decision explains most of the rest of the design. Because state lives in the daemon, the same resources are reachable from the web UI, the CLI, HTTP with SSE, a Unix domain socket, MCP, and native tools. Because state is persisted, the README describes SQLite-backed stores and a local-first default where runtime state stays on the operator's machine unless a configured provider or extension owns an external boundary. Because the daemon owns discovery and lifecycle, extensions plug into declared contracts instead of reaching around them.

The control surfaces are managed with explicit commands: compozy daemon start, compozy status and compozy daemon stop. Structured output is available through -o json, which is the detail that makes the CLI usable from another agent or program rather than only from a human shell.

One boundary worth noting is that this is a home-scoped daemon, not a cluster. There is a Gateway for pairing devices and exposing surfaces an operator enables, and the README describes remote access as explicit rather than default. Nothing in the README suggests horizontal scaling or multi-tenant isolation, so treat it as an operator tool for one machine or a small set of paired devices.

## Installing the v0.3 beta and running a first session

The README lists four install channels for the v0.3 beta and is unusually explicit about which ones not to use. Homebrew still serves the deprecated v0.2 line during the beta window and is omitted on purpose; the compozy formula returns with v0.3.0 stable. Go's @latest also resolves the v0.2 stable line while v0.3 is in beta, so the Go path requires the explicit release tag from the latest release page.

The verified installer pins the latest published beta and verifies Sigstore provenance before installing on macOS or Linux. That provenance check is the reason to prefer it over a manual download.

```bash
curl -fsSL https://compozy.com/install.sh | sh
```

If you would rather keep the binary in a Node-managed environment, the npm package is published under a beta tag:

```bash
npm install -g @compozy/cli@beta
```

Building from source is a plain Go build and is the path that lets you read the code you are about to run:

```bash
git clone https://github.com/compozy/compozy.git
cd compozy
go build -o ./bin/compozy .
```

Once the binary is on your PATH, the first real step is not starting the daemon but checking which configuration the process will read. Global defaults live in ~/.compozy/config.toml and a workspace can override supported fields through .compozy/config.toml, with explicit command flags winning over workspace configuration, which wins over global configuration, which wins over built-in defaults. Verify that chain before you author anything.

```bash
compozy config path
compozy config validate
compozy config show -o json
```

With the configuration confirmed, start the daemon and create a session against an agent definition. Agent definitions live under ~/.compozy/agents/<name>/ or .compozy/agents/<name>/, each with an AGENT.md and optionally an agent-local mcp.json; workspace definitions override global ones as a whole. The README's own example uses an agent named general.

```bash
compozy daemon start
compozy agent list -o json
compozy session new --agent general
```

After that, compozy status reports the daemon state and compozy daemon stop shuts it down. The README does not document a rollback procedure for a failed beta upgrade, which is worth knowing before you replace anything.

## Where CompozyOS is the wrong tool

The README carries its own warning, and it is not boilerplate: the v0.3 line is in beta, and the previous v0.2.15 product is deprecated and maintained only for critical fixes on the legacy/v0.2 branch. The migration guide is described as something to read before replacing an existing v0.2 installation. If you are running v0.2.15 in anything that matters and cannot schedule a migration, this is not the moment to move.

There is a second, quieter constraint in the task model. Authored task files remain portable Markdown with typed frontmatter, but the v0.3 runtime imports them into durable tasks and executes them through Loops. It does not revive the v0.2 tasks run pipeline. Anyone with automation built around that command is looking at a rewrite, not an upgrade, and the README points at the migration guide for the exact schema and command changes.

The third case is simpler. If your agent work is interactive and short-lived, a daemon that persists sessions, coordinates ACP processes and owns SQLite-backed stores is overhead you will not recover. The same applies if you need a stable release channel today: the Homebrew formula is deliberately absent during the beta window, and Go's @latest install path resolves to the deprecated line unless you pin a tag. Those are friction points, not bugs, but they are friction you should price in before adopting.

## Extensions, the SDKs, and what the plugin model costs you

Extensions are the part of CompozyOS with the most moving pieces. They add versioned resources and runtime behavior through declared provide surfaces, and the daemon owns discovery, enablement, trust decisions, lifecycle and hooks. The README is emphatic that extensions do not bypass public runtime contracts, which is a governance choice: you get a stable boundary, and you give up the ability to reach into internals.

The scaffolding is short. The README advertises building one in three commands:

```bash
compozy extension init hello --template tool-provider-go
compozy extension dev hello
compozy tool invoke ext__hello__search --workspace . --input '{"query":"compozy"}'
```

There are two extension shapes. Executable extensions are code-first: you declare the tool once in code and compozy extension build generates the manifest. Resource-only extensions can instead hand-write extension.toml and use the same build, dev, reload and watch loop without running extension code. That split is sensible, but it also means the manifest is generated in one case and authored by hand in the other, so the two paths will drift in documentation and in tooling unless the project keeps them in step.

SDK support is published and version-matched to the daemon: @compozy/extension-sdk on npm under MIT, and github.com/compozy/compozy/sdk/go. Version matching is the detail that matters here. An extension built against a mismatched daemon is the most likely source of confusing failures, and the README does not describe what compatibility checking looks like at load time. The operational commands for inspecting what is installed are compozy extension list, compozy extension status <name>, compozy extension provenance <name>, and compozy extension logs <name> --follow.

## How CompozyOS differs from a plain agent CLI plus cron

The honest alternative is not another agent framework. It is the setup most teams already have: an ACP-compatible CLI such as Claude Code, a crontab entry or a CI schedule, and a directory of shell scripts that stitch them together. That stack is genuinely cheaper to start with, and for a single nightly job it is the right answer.

The difference is what survives. With cron and shell scripts, the run state lives in log files and exit codes, permissions are whatever the invoking user has, and an approval step means blocking a process or writing a notification script. CompozyOS moves those concerns into the daemon: sessions and Loop runs are daemon-owned, approvals and permissions are runtime objects, and events and resource state are persisted and readable from several surfaces. The README describes approvals, permissions, run state, artifacts and agent activity as inspectable while work continues in the background. That is the actual product, not the agent execution.

A second difference is the agent boundary. CompozyOS does not replace Claude Code, OpenClaw or Hermes; it coordinates them through ACP. If you have already standardised on one of those CLIs, the migration cost is configuration rather than retraining. If you have built your own harness around a different protocol, the ACP requirement is a hard constraint rather than a preference.

The cost of that coordination is a daemon you now have to run, supervise and upgrade. There is a self-update dependency in the module graph and the README mentions managed updates in the installation guide, but it does not document rollback. Plan for a version you can pin and revert to.

## Licence, release cadence and the upgrade bill

CompozyOS is MIT licensed, and the extension SDKs are published under MIT as well. That is permissive and unsurprising for a developer tool. The licence does not settle the questions that actually cost you money, which are about update cadence and the beta channel.

The release history shows three betas in the final week of August 2026: v0.3.0-beta.19, beta.20 and beta.21, the last pushed on 2026-08-27. That cadence is normal for a beta line and it is also the upgrade cost. If you track the beta channel through the verified installer or npm install -g @compozy/cli@beta, you are opting into frequent movement. Pinning is possible on the Go path, where the README instructs you to install with an explicit release tag rather than @latest, and that is the channel to prefer if you want reproducible builds.

The upgrade story has one gap worth naming. The README tells you to start with the migration guide before replacing an existing v0.2 installation, and it points at the installation guide for installer flags, Linux packages, source builds, verification and managed updates. It does not describe a rollback path for a failed beta upgrade, and the v0.2 line is maintained only for critical fixes. Treat the migration as a one-way door until the project documents otherwise.

On licence implications specifically: MIT places few obligations on you, but extensions you distribute carry their own licence terms, and the README does not describe a policy for third-party extension licensing. That is a question for your own legal review, not something the repository answers.

## Conclusion

Adopt CompozyOS if you already run an ACP-compatible agent CLI and want its sessions, schedules and approvals to outlive the terminal, and if you can accept beta software on the v0.3 line. Do not adopt it if you are on a v0.2.15 installation you cannot migrate this week, or if you need a stable release channel with a Homebrew formula, since the README states the formula returns only with v0.3.0 stable. Before anything else, run compozy config path and compozy config validate against a fresh home, and read MIGRATION_GUIDE.md end to end if a v0.2 home already exists on the machine.

## FAQ

### What is CompozyOS and who is it for?

It is described in the README as an operating system for AI agents, built first for developers and technical operators. It turns loops, triggers, cron, memory, permissions, approvals and observability into one product around the agent CLIs you already use.

### How do I install CompozyOS?

The v0.3 beta ships through a verified installer that checks Sigstore provenance on macOS or Linux, an npm package at @compozy/cli@beta, an explicit Go release tag, or a source build with go build. The README states Homebrew still serves the deprecated v0.2 line and is omitted during the beta window.

### Which agent CLIs does CompozyOS run?

The README names ACP-compatible CLIs: Claude Code, OpenClaw and Hermes. CompozyOS coordinates them through the daemon rather than shipping its own agent.

### What is code AI?

The README does not define this term. What CompozyOS does document is that it drives ACP-compatible agent CLIs and keeps sessions, Loop runs and approvals in daemon-owned state.

## Sources

- [Official documentation](https://compozy.com)
- [Official README](https://github.com/compozy/compozy#readme)
- [Project repository](https://github.com/compozy/compozy)
- [Release notes](https://github.com/compozy/compozy/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/compozy-compozy