Desktop app operations

Start with structured state:

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

compozy app diagnose reads the current boot through the app control socket. When the app is not running, it reads the latest persisted report instead, so a failed start does not require a healthy daemon. A present but unresponsive socket returns its control error.

Copy or export startup diagnostics

In the boot window, select Load diagnostics. Copy diagnostics copies the redacted report. Export diagnostics creates a local archive only after that explicit action and uploads nothing.

From a terminal:

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

--yes confirms the local write. The command refuses an existing output file or symbolic link. The archive contains manifest.json and may include bounded, redacted tails from the current boot's desktop.log and desktop-bootstrap.jsonl. It excludes compozy.log, raw logs, databases, configuration, credentials, sessions, and transcripts.

Log paths

Both supported desktop platforms use the active COMPOZY_HOME:

The default home is ~/.compozy.

Linux launch failures

Install the package for your x64 Linux system. The AppImage carries a static runtime and needs no libfuse2 package. Where kernel FUSE support is unavailable:

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

If Electron exits before the product window opens, inspect desktop.log, verify the downloaded artifact against the release checksum, and reinstall the current package. Do not add graphics environment overrides to a global shell profile.

Recover an app update

If app apply fails, download the current package for your architecture from the GitHub release and install it over the existing app. The runtime home and session data live outside the application bundle.

compozy app status -o json
compozy update --check -o json

Recover a runtime update

When an update operation reports failed:

1. Save the reported error code from compozy app diagnose -o json.
2. Follow the reported action without deleting the active runtime, staging directory, or home data.
3. Run compozy app retry after resolving the cause.
4. Confirm healthy state with compozy app status -o json.

For an operator-managed runtime, use the package-manager command in the update result. The app never replaces a Homebrew, npm, Go, Linux package, or other externally managed install.

Recover the desktop channel

A release operator repairs a bad desktop channel through the GitHub-backed channel authority, not by editing a manifest in place. See Desktop release operations.

Local security boundary

The desktop app loads the daemon-served product from the same machine and creates no second public listener. Remote access is a separate trust boundary and must use the authenticated Gateway. Do not expose the local daemon port directly to a network.