Installation

Use the desktop app for the primary interactive setup. Use the compozy command when you want a terminal-managed runtime, headless operation, or automation. Both surfaces use the same local runtime and ~/.compozy home.

Before You Begin

The desktop app supports macOS on Apple silicon and Intel, and Linux on x64. Before installing either surface, make sure you have:

• An install method that fits your machine. For the desktop app, use the package for your architecture from GitHub Releases. For the compozy command during the v0.3 beta, use the verified installer, npm's beta channel, or the explicit Go beta version. Homebrew returns with v0.3.0 stable. The verified binary installer requires curl, tar, and either sha256sum or shasum. It uses a local cosign when available; otherwise it downloads a pinned temporary cosign verifier before checking CompozyOS release provenance.
• At least one supported agent CLI such as Claude Code, OpenClaw, Hermes, or another ACP-compatible agent runtime you already use.
• At least one provider authenticated in its native way. Direct ACP providers such as Claude Code, Codex, Gemini CLI, OpenCode, Hermes, and OpenClaw use their own CLI login/session state by default. The direct pi provider uses Pi's /login and auth file by default. Wrapped API-key providers such as OpenRouter, z.ai, Moonshot/Kimi, Vercel AI Gateway, xAI, MiniMax, Mistral, and Groq use auth_mode = "bound_secret" by default and need an env: or vault:providers/<provider>/<slot> credential configured for the daemon.

Example for a built-in wrapped provider:

export OPENROUTER_API_KEY="..."

Install the desktop app

Download the package whose name matches your machine from the CompozyOS GitHub release:

On macOS, open the matching notarized .dmg, then drag CompozyOS to Applications. On Linux, verify the package against the release checksums.txt before installing or running it.

AppImage mounting requires FUSE 2. On Ubuntu and Debian, install libfuse2; newer distributions may name the package libfuse2t64. If FUSE is unavailable, use the built-in extraction fallback:

./CompozyOS-<version>-linux-x64.AppImage --appimage-extract-and-run

Open the app after installation. It first attaches to a healthy runtime already running on the machine. Otherwise it starts the installed runtime or verifies and installs the runtime bundled inside the app. A clean first run does not need a network connection. Continue with Desktop app.

Install the compozy command

Option 1: verified binary installer

Use the verified installer for a standalone beta install on macOS or Linux:

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

The installer pins the latest published beta (currently v0.3.0-beta.5), downloads a pinned temporary cosign verifier when cosign is not already on PATH, downloads the matching GitHub release archive, verifies checksums.txt against checksums.txt.sigstore.json, verifies the archive checksum, installs compozy, runs compozy version, and opens compozy install when an interactive terminal is available.

Use flags when you need a pinned or scripted install:

curl -fsSL https://compozy.com/install.sh | sh -s -- --version v0.3.0-beta.5 --dir "$HOME/.local/bin"

curl -fsSL https://compozy.com/install.sh | sh -s -- --skip-bootstrap
curl -fsSL https://compozy.com/install.sh | sh -s -- --dry-run

Environment variables are equivalent for automation:

curl -fsSL https://compozy.com/install.sh |  COMPOZY_VERSION=v0.3.0-beta.5 COMPOZY_INSTALL_DIR="$HOME/.local/bin" COMPOZY_SKIP_BOOTSTRAP=1 sh

If the target directory is not on your PATH, the installer prints the exact directory to add.

Option 2: npm beta channel

Use npm when you want package-manager-owned updates on the beta channel:

npm install -g @compozy/cli@beta

Option 3: explicit Go beta

Go's @latest still resolves the v0.2 stable line during beta. Pin the current v0.3 prerelease:

go install github.com/compozy/compozy@v0.3.0-beta.5

Option 4: Linux packages

Tagged releases publish archive checksums, checksums.txt.sigstore.json, SBOMs, and Linux .deb and .rpm packages. Download the package for your architecture from the GitHub release, verify it against checksums.txt, then install it with your distribution package manager.

Option 5: build from a repository checkout

Use this when you are already working from the CompozyOS source tree or want a local build artifact you control explicitly. This path requires Go 1.26.4 or later.

git clone https://github.com/compozy/compozy
cd compozy
go build -o ./bin/compozy .
export PATH="$PWD/bin:$PATH"

Verify the command install

Confirm that the binary is available:

compozy version

If your shell reports command not found, fix PATH first. Do that before you continue.

Bootstrap the command-managed home

The verified binary installer runs this step automatically when it can access an interactive terminal. If you used --skip-bootstrap, a managed install, a Linux package, or a source build, run the interactive bootstrap once:

compozy install

This creates or updates:

• ~/.compozy/config.toml
• ~/.compozy/agents/general/AGENT.md

The bootstrap flow lets you pick a default provider and model for the built-in general agent.

Manage the command install

Use compozy config path to inspect the exact global and workspace config files CompozyOS will read, and use compozy config validate after manual edits. compozy config show, compozy config list, and compozy config get <path> always redact environment-backed MCP and config values before printing. From the project tree, use compozy config validate --repair-env when a workspace .env needs a bounded repair. Pass --workspace <id|name|path> only to override the inferred project.

compozy update keeps a beta install on newer v0.3 prereleases and never offers the v0.2 stable line. Use compozy update --check for a status-only check. Managed installs defer to their package manager and return the beta-safe command instead of mutating files directly: npm install -g @compozy/cli@beta, the hosted installer, or the pinned go install command for the current beta (v0.3.0-beta.5). Homebrew guidance returns only after the formula ships v0.3.0 stable. Windows direct-binary installs remain manual in this first cut. compozy uninstall removes runtime launch artifacts idempotently and preserves ~/.compozy unless you explicitly pass --purge --force.

Sanity Check the Runtime Inputs

Before moving to Quick Start, verify these four things:

1. compozy version succeeds.
2. compozy install completed, either through the verified binary installer's automatic bootstrap, a managed install, a Linux package, or a manual run, and created ~/.compozy/config.toml.
3. compozy config validate reports a valid config.
4. Your selected provider is authenticated. For native CLI providers, run the provider's own login command first; for bound_secret providers, make sure the daemon can resolve the configured env: or vault: secret.

Next step

Desktop users should continue to Desktop app. Command users can continue to Quick Start, which assumes the binary works, ~/.compozy exists, and the selected provider is authenticated.