Desktop app

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

First runCopy Anchor Link

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 locallyCopy Anchor Link

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 diagnosticsCopy Anchor Link

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 ownershipCopy Anchor Link

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.

UpdatesCopy Anchor Link

compozy update is the single host update command:

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

Click Update in the menubar or Settings to download, install, and restart. If the app owns the runtime, one app package carries both updates; the new app starts its bundled runtime. The app stays open while its native installer prepares the verified package. A closed app is staged for the next launch. Standalone runtime updates keep their existing update path.

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.

RecoverCopy Anchor Link

If an app update fails, click Retry update or run compozy update again. There is no need to cancel a completed failed operation in Settings. If the desktop itself cannot start, inspect and retry startup:

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 stepCopy Anchor Link

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