Desktop app

The desktop app and the compozy command use the same local daemon, configuration, workspaces, and session history.

First run

Every packaged app includes the matching CompozyOS runtime. First run does not need a network connection to install it.

The app follows one boot ladder:

1. Attach to a healthy daemon already running in the current COMPOZY_HOME.
2. Start the runtime already installed at $COMPOZY_HOME/bin/compozy.
3. If that file is absent, verify the bundled runtime, copy it into the home, and start it.

The boot window reports the active phase. Runtime start retries use bounded backoff; a terminal failure leaves Retry operation, Open logs, Load diagnostics, and Quit available. The app never executes a bundled runtime that fails its embedded integrity check.

Develop locally

From the repository root:

make desktop-dev

This builds the web app, starts the development daemon, waits for readiness, and opens Electron. A source checkout does not imitate the packaged runtime bundle.

Startup diagnostics

Select Load diagnostics in the boot window, then expand Technical details. The report includes the boot ID and phase, app and runtime versions, runtime ownership, a safe error, and the previous crash marker. It excludes raw paths, log contents, and secrets.

Use Copy diagnostics for the redacted report or Export diagnostics for a local archive. Export requires your action, uploads nothing, and never deletes runtime data. The same operations are available without a healthy daemon:

compozy app diagnose -o json
compozy app diagnose --bundle --yes -o json
compozy app diagnose --bundle --yes --bundle-output ./desktop-diagnostics.tar.gz -o json

Without --bundle-output, the archive is written under $COMPOZY_HOME/support-bundles/. It contains manifest.json and may contain bounded, redacted tails from desktop.log and desktop-bootstrap.jsonl. It is separate from the daemon-owned support bundle.

Runtime ownership

Attaching does not transfer ownership. Quitting the app never stops the daemon, including one the app started. Use the runtime control surface when you intend to stop it.

Inspect or open the app from a terminal:

compozy app status -o json
compozy app open
compozy app open /workspaces

The preserved compozy app verbs are open, status, retry, and diagnose.

Updates

compozy update is the single host update command:

compozy update --check -o json
compozy update -o json
compozy update --cancel -o json

An update checks the runtime and, when installed, the app. Apply runs runtime first. A running app then installs its verified artifact; a closed app is staged for the next launch. Cancel succeeds only while the operation has no live executor lease.

On Linux, automatic app-track installation is available only for the AppImage. A .deb install must be updated by downloading and installing the current .deb package over the existing app.

The same host-global operation is available through GET /api/settings/update, POST /api/settings/update/apply, and POST /api/settings/update/cancel over HTTP and UDS. Apply accepts a non-empty targets array, such as {"targets":["runtime","app"]}; runtime is listed first, and managed or unavailable tracks are omitted. Status can report available, applying, staged, blocked, failed, updated, or up-to-date; app status also carries the operation ID, phase, and progress when present.

For a managed runtime, CompozyOS returns the exact package-manager command and does not replace the binary.

Recover

If an update operation reports failed, read diagnostics before starting another mutation:

compozy app diagnose -o json
compozy app retry
compozy app status -o json

Retry is limited to disposable desktop metadata and a runtime process proven to be app-owned. It never stops an operator-managed process or resets config.toml, databases, credentials, sessions, or the CompozyOS home.

For log locations and manual recovery, see Desktop app operations.

Next step

Continue to Quick Start, or open the same runtime in the Web UI.