Desktop app
Start CompozyOS from the desktop, attach to the local runtime, and manage app and runtime updates.
4 min read6 pages in Getting Started
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:
- Attach to a healthy daemon already running in the current
COMPOZY_HOME. - Start the runtime already installed at
$COMPOZY_HOME/bin/compozy. - 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.
A config.toml that cannot be loaded is reported once, without retries. The boot window names the
file and the settings it does not recognize, or the line of invalid TOML, and adds Open config
file. See Troubleshooting.
The app waits instead of retrying when the runtime is busy:
- While another update, restart, or start holds the runtime, the boot window says "Another update
or restart is in progress" with that process when it is known, and continues when it finishes.
This wait does not use a start attempt. After 10 minutes it stops with the code
update_lock_held. - A runtime binary that is missing or not allowed to run is reported once, without retries.
- With the app open, a runtime that stops answering is given 45 seconds, and after that for as long as a runtime process is still alive (the one the app was connected to, a replacement that is starting, or the process running a restart or update), up to 10 minutes. The app resolves the runtime again only when no such process is left.
The app opens as soon as the runtime answers, while interrupted sessions are still resuming. A notice on the desktop names the step ("Resuming interrupted sessions", for example) and says that reading works and sending opens again when it finishes. It clears by itself. Runtimes that predate this behavior open the app once they are fully ready, as before.
After a restart on the same runtime version the window keeps its page and refreshes its data, so open windows and drafts stay. The window reloads when the runtime now serves another version, when the page failed to load during the outage, or when the runtime predates this behavior.
Develop locally
From the repository root:
make desktop-devThis 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 jsonWithout --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 /workspacesThe 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 jsonClick 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.
Recover
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 jsonRetry 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.