Desktop and updates
Resolve Zyron launch, window, architecture, packaged update, and reinstall problems without deleting useful state.
Treat the desktop application, its local server, and the installed provider runtimes as separate layers. A window problem does not automatically mean your repositories, provider credentials, or Zyron workspace data are damaged.
Zyron will not launch
Work through these checks in order:
- Confirm the installer matches your operating system and CPU architecture.
- Fully quit any existing Zyron process.
- Start Zyron again from the normal application launcher.
- Restart the operating system if a previous process cannot be terminated cleanly.
- Re-download the current installer from the official download page.
- Reinstall over the current application without deleting workspace data.
On macOS, use the Arm64 build for Apple Silicon and the x64 build for Intel. On Linux, match the
AppImage to your CPU (uname -m: x86_64 uses the Intel build, aarch64 uses ARM64), make it
executable, and install FUSE 2 if the AppImage cannot mount itself:
chmod +x Zyron*.AppImageIf your distribution has no FUSE 2 package, run the bundle without mounting it:
./Zyron*.AppImage --appimage-extract
./squashfs-root/zyronReplacing the application bundle and deleting Zyron’s local data are different operations. As a rule, reinstall the application first. Preserve repositories, uncommitted changes, task evidence, and any data directory before considering destructive cleanup.
Closing while chats are still running
When a desktop quit would interrupt running or connecting chats, Zyron lists those chats before closing.
- Choose Cancel to keep the app and current work open.
- Choose Quit to stop the listed work and close.
- Leave Resume chats automatically enabled when eligible chats should receive a continuation turn on the next launch.
Automatic resume is guarded rather than unconditional. Zyron skips a remembered chat when it completed, was archived or deleted, already started newer work, or no longer belongs to a live project. If the local server cannot record the resume intent within the bounded quit wait, Zyron falls back to interruption and still allows the desktop app to close; do not assume that fallback work will resume automatically.
The checkbox choice persists for later quits. Review it when a task must not continue without fresh supervision.
The window is blank or unresponsive
A blank window can come from the renderer, the local server, graphics state, or a process left over from an earlier launch.
- Wait briefly for initial startup and provider-health probes.
- Fully quit Zyron rather than only closing the window.
- Start it again with no other Zyron instance running.
- Disconnect unusual display, proxy, or security software only when you can do so safely and reversibly.
- Record whether the window is blank immediately or only after opening a specific project or surface.
- Capture the operating system, Zyron version, and exact time before restarting again.
When only one project or task triggers the problem, report that boundary. It is more useful than “the app is blank.”
Windows or Linux title bar looks wrong
Open Settings → Appearance → Use custom title bar to switch between Zyron’s frameless title bar and the operating system’s title bar. A restart is required because Electron chooses the window frame before the renderer starts; use the offered relaunch action after saving the preference.
The custom title bar is supported only on Windows and Linux. Some Linux window managers integrate better with the system title bar. On Windows, the custom frame keeps Zyron’s own minimize, maximize, restore, and close controls.
The local server does not become ready
Zyron’s desktop UI depends on its local application server. Repeated connection or startup errors can result from:
- Another Zyron process using the local runtime state
- A partially terminated previous launch
- A blocked local process
- A damaged or incompatible application installation
- Security software preventing the packaged server from running
Fully quit every Zyron process, then relaunch. Do not expose or forward Zyron’s local server ports as a troubleshooting shortcut.
The packaged update failed
- Preserve important Git work.
- Close active provider turns and terminal processes when practical.
- Fully quit Zyron.
- Start it again and retry the update once.
- If the updater still fails, download the newest installer from ai.zyron.site/install or GitHub Releases.
- Install the new application over the existing application.
- Launch Zyron and verify the displayed version before resuming important work.
An update failure does not prove that local task data was deleted. Avoid combining an update recovery with manual data-directory cleanup.
A downloaded update is waiting
Zyron continues checking on its normal four-hour schedule while a downloaded update waits for installation. Check for Updates also checks immediately. If a newer compatible release is available, Zyron downloads it and replaces the pending version; a failed check keeps the already verified download. Installation waits until checking and downloading finish.
Update a Mac from an iPhone or iPad
In companion builds that support remote updates, open Settings → Connections, select the Mac, then open Software Update. You can check, download, and choose Restart & Install for the downloaded version. This requires an approved connection to the packaged Zyron Remote app on macOS; older desktop builds must first be updated on the Mac.
Finish running chats, queued tasks, approvals, and development servers before installing. The Mac refuses a remote restart when it detects that work is still active or cannot establish that it is idle. Confirm the displayed version and the temporary connection interruption. The app reconnects after Zyron restarts; check Installed version to confirm completion. A dropped connection alone does not prove installation succeeded. There is no need to delete local data or pair again for an ordinary update.
Zyron opens but providers changed after an update
The application update and provider CLI updates are independent. After updating Zyron:
- Restart the app so provider discovery runs against the current environment.
- Check each enabled provider’s detected executable and authentication state.
- Remove stale custom binary paths.
- Update the provider runtime through its own supported method when Zyron reports that it is outdated.
- Start a new provider session when protocol or capability negotiation changed.
Continue with Provider troubleshooting.
Source build and packaged build behave differently
A development checkout and a packaged release may use different executable paths, environment variables, data locations, update behavior, and build-time configuration.
When reporting a problem, state whether you are using:
- A packaged release
- A locally built desktop application
- A website development server only
- A specific branch or commit
Do not use a successful website build as evidence that the packaged desktop runtime works.
Safe reinstall checklist
- Important repository changes are committed, stashed, copied, or pushed
- The correct installer and architecture were selected
- Every Zyron process was fully closed
- The application was replaced before any data was deleted
- The version was checked after launch
- Provider detection and authentication were rechecked
- A small test task was completed before resuming important work
Still failing
Continue with Diagnostics, then prepare a focused report using Report a problem.
macOS requirement in 1.0.9
The app bundle and updater enforce macOS 13 or later, matching the bundled native tools. On an older system, update macOS before attempting this release. See installation requirements.
Offline database compaction in 1.1.0
If normal shutdown maintenance cannot reclaim a large legacy database, close every Zyron process and every external SQLite client first. Run the installed CLI command with the database's absolute path:
zyron-compact-database "$HOME/.zyron/userdata/state.sqlite"For Beta, explicitly select $HOME/.zyron-beta/userdata/state.sqlite; custom homes require their actual path. The command never discovers another channel's database. On PowerShell, use a quoted path such as "$env:USERPROFILE\.zyron\userdata\state.sqlite".
Compaction holds Zyron's lifecycle lock, refuses pending migration recovery and verifies a private copy's integrity, row counts and identity before replacement. It preserves retained rows and migration backups. Allow about 125% of live-page space plus 64 MiB on the same volume; insufficient space requires freeing space, not deleting application history to force success.
Keep all clients closed until completion. Cancellation before replacement preserves logical data, although WAL checkpointing may already have changed physical bytes. A failure after replacement explicitly reports that the compact database was installed; preserve it for inspection. Windows does not promise directory-entry durability across sudden power loss. This is maintenance, not emergency disk-recovery or universal completion-time assurance.
Source evidence for 1.1.0: application source d80787e3e4d8829a35a64b111e6fcbe5f51cf037; docs/releases/1.1.0-source-audit.md, docs/core-concepts.md, docs/providers.md, docs/internationalization.md and docs/sqlite-space-reclamation.md.