Anyone can prompt an agent. Making agents work continuously is still an engineering project: loops,
triggers, cron, permissions, approvals, observability, and the glue scripts that hold them
together. CompozyOS turns that entire agent stack into one product, a complete environment to
create, automate, and supervise agent work with the agent CLIs you already use (Claude Code,
Codex, and Cursor). Built first for developers and technical operators.
[!NOTE]
v0.4.0 is the first stable CompozyOS release. The previous v0.2 product has reached end of life
and receives no further releases. Start with the migration guide before
replacing an existing v0.2 installation.
✨ Highlights
- Create. Sessions, agents, Loops, and capabilities are objects you author once and reuse, not
scripts you rewrite per run.
- Automate. Cron schedules, webhooks, and triggers keep work running with no terminal open.
- Supervise. Approvals, permissions, run state, artifacts, and agent activity stay inspectable
while work continues in the background.
- Work survives the terminal. Sessions and Loop runs belong to the daemon, so closing one client
does not erase the work.
- Runs the agents you already use. ACP-compatible CLIs (Claude Code, Codex, and Cursor)
operate the same daemon-owned state.
- Batteries included. One runtime, one state model: loops and approvals are core
objects, not plugins, reachable from web, CLI, HTTP/SSE, UDS, MCP, and native tools.
- Local-first by default. One Go binary and SQLite-backed stores keep runtime state on the
operator's machine unless a configured provider or extension owns an external boundary.
- Remote access stays explicit. The Gateway
pairs devices and exposes only the private or public surfaces an operator enables.
- Built to extend. Agents, skills, capabilities, hooks, and extension kits plug into
explicit runtime contracts.
📦 Installation
Verified installer
The installer pins the latest published release and verifies Sigstore provenance before installing
the binary on macOS or Linux.
curl -fsSL https://compozy.com/install.sh | sh
Homebrew
brew install compozy/compozy/compozy
NPM
npm install -g @compozy/cli
Go
Install with the explicit tag shown on the
latest release:
go install github.com/compozy/compozy@<release-tag>
From Source
git clone https://github.com/compozy/compozy.git
cd compozy
go build -o ./bin/compozy .
The installation guide covers
installer flags, Linux packages, source builds, verification, and managed updates.
🔄 How It Works
People and agents send commands through public control surfaces. The home-scoped 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 instead of maintaining a
parallel model.
Daemon Runtime Model
compozy daemon start, compozy status, and compozy daemon stop manage the local daemon.
Sessions, tasks, Loop runs,
automation and tools keep explicit owners and workspace boundaries. Use
structured CLI output (-o json), HTTP/SSE, UDS, MCP, or native tools when another agent or program
needs to manage the same resources.
Task Schema v2
Authored task files remain portable Markdown with typed frontmatter. The v0.3 runtime imports them
into durable tasks and executes them through Loops; it does not revive the v0.2 tasks run pipeline.
See Migrate from v0.2.15 for the exact schema and command changes.
⚙️ Config Files
Global defaults live in ~/.compozy/config.toml; a workspace can override supported fields through
.compozy/config.toml. Explicit command flags win over workspace configuration, which wins over
global configuration and built-in defaults.
compozy config path
compozy config validate
compozy config show -o json
Configuration, credentials, and provider-home policies have different owners. Follow the
configuration guide instead of copying
v0.2 state into a v0.3 home.
Reusable Agents
Agent definitions live under ~/.compozy/agents/<name>/ or .compozy/agents/<name>/. Each definition
has an AGENT.md and may include an agent-local mcp.json. Workspace definitions override global
definitions as a whole.
compozy agent list -o json
compozy agent info general -o json
compozy session new --agent general
🔌 Extensions
Extensions add versioned resources and runtime behavior through declared provide surfaces. The daemon
owns discovery, enablement, trust decisions, lifecycle, and hooks; extensions do not bypass public
runtime contracts.
Build one in three commands
compozy extension init hello --template tool-provider-go
compozy extension dev hello
compozy tool invoke ext__hello__search --workspace . --input '{"query":"compozy"}'
Executable extensions are code-first: 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. Walkthrough:
Build your first extension.
SDK support
@compozy/extension-sdk (npm, MIT) and github.com/compozy/compozy/sdk/go are published and
version-matched to the daemon.
Extension CLI
compozy extension list -o json
compozy extension status <name> -o json
compozy extension provenance <name> -o json
compozy extension logs <name> --follow
Learn more
Build an app
Use @compozy/client for TypeScript or github.com/compozy/compozy/sdk/go/client for Go to connect
an external app to your running daemon. Both clients provide typed operations and agent streams;
app tokens authorize trusted browser origins on the local listener.
Follow the Build an app tutorials for Node, a server-backed chat UI,
browser access, Go, and token administration. The API reference
includes generated SDK calls for each operation. These app SDK surfaces are experimental in 0.4;
pin the exact version matching your daemon.
🚀 Quick Start
Bootstrap the home, start the daemon, enter the repository you want agents to work in, and create one
durable session. CompozyOS infers and registers the workspace from the current directory; use
--workspace <id|name|path> only when you need an override.
compozy install
compozy daemon start
compozy session new --agent general --name first-run
The Quick Start continues through the
first prompt, live attachment, inspection, and cleanup.
🧩 Skills
Skills are daemon-discovered resources with explicit source and scope. Use the structured skill and
marketplace surfaces to inspect what is active instead of copying v0.2 setup directories forward.
compozy skill list -o json
compozy skill inspect <name> -o json
compozy marketplace search --kind skill --query <term> -o json
🧠 Workflow Memory
Workflow memory is ordinary repository files under .compozy/tasks/<name>/memory/, written and read by
the spec-cycle skills. The v0.2 workflow-memory files remain repository artifacts; they are not
imported as hidden runtime state.
🤖 Supported Agents
CompozyOS runs ACP-compatible agent CLIs and adapters. The active provider catalog and each agent's
runtime settings are runtime truth; inspect them before selecting a model or reasoning mode. See the
provider guide for authentication and
provider-home policies.
📖 CLI Reference
The generated CLI reference is authoritative for verbs,
flags, structured output, and exit behavior. Start with:
compozy --help
compozy version
compozy doctor -o json
Documentation
🛠️ Development
CompozyOS is a Go and Bun monorepo. Start the daemon with automatic Go rebuilds and the web UI with
Vite HMR:
make dev
To populate the Northstar Pay demo and leave its daemon running in the background:
make demo-seed
# Optional isolated home and secondary port:
make demo-seed DEMO_HOME="$HOME/.compozy-demo-other" DEMO_PORT=2125
This builds the daemon and Web bundle, replaces the seed-owned scenario, and starts
the demo at http://localhost:2124 using ~/.compozy-demo by default. The main
instance is unchanged. To reseed a running demo, first stop its daemon with
COMPOZY_HOME="$HOME/.compozy-demo" ./bin/compozy daemon stop (use your custom home
if overridden). The raw go run ./scripts/demo-seed --home <path> command remains
available for data-only seeding. Existing demos in ~/.agh can still be selected
explicitly with DEMO_HOME.
To prepare the same demo and open it in the Electron desktop shell:
make demo-seed-desktop
# The same overrides apply:
make demo-seed-desktop DEMO_HOME="$HOME/.compozy-demo-other" DEMO_PORT=2125
The desktop shell uses the demo home for its runtime connection and Electron
profile. Quitting Electron leaves the demo daemon running in the background.
As with demo-seed, stop an already-running demo before reseeding it.
Run the affected local gate before committing or pushing:
make gate
Delivery finishes in the draft PR: wait for every required CI check to pass on its current head.
Read AGENTS.md and the surface-specific instructions before editing.
Star History
🤝 Contributing
Contributions are welcome. Open an issue or pull request, keep public behavior agent-manageable, and
run make gate before sending changes, then keep the PR until its current-head CI is green. Security reports belong in the repository's
private security channel, not a public issue.
Contributors
Thanks to everyone who has contributed to CompozyOS.
📄 License
CompozyOS is distributed under the MIT License.
