Update the Desktop app

Desktop auto-update is opt-in in v3.0.0-beta.15. Before enabling it, install the standard ak CLI separately and keep the CLI and Desktop on the same release.

ak --version
ak self-update --check

The check uses your saved update channel, or the running release binary's channel when none is saved, then stable. It reads signed release metadata and does not install an update. The result reports the channel and its source. Confirm that the reported channel is the one you intend to follow. If the CLI belongs to Homebrew or Scoop, use the manager command AgentKit reports instead of replacing that CLI in place.

On macOS, a Desktop app opened from Finder can inherit a minimal PATH. When you enable auto-update without a saved CLI path, Desktop checks PATH, then ~/.local/bin/ak, /opt/homebrew/bin/ak, and /usr/local/bin/ak. Each candidate still passes normal path and executable validation, and a candidate whose version does not match Desktop is skipped. If no matching CLI is found, install or expose the same-release CLI before enabling auto-update. Package manager detection still applies to the resolved candidate.

Know the platform boundary

Windows does not replace Desktop in-process. After staging, quit the running CLI or Desktop so the handoff helper can finish the verified swap.

What the signed flow verifies

Before staging a candidate, AgentKit verifies the signed channel pointer, the immutable manifest and its digest, release compatibility, and each selected artifact's declared size and SHA-256. The matching CLI and Desktop candidates are staged under:

$AGENTKIT_HOME/cache/binaries/<version>

The paired transaction is recorded at:

$AGENTKIT_HOME/updater/pending-binary-update.json

The default $AGENTKIT_HOME is ~/.agentkit on macOS and Linux and %USERPROFILE%\.agentkit on Windows.

Apply and restart

1. In Desktop update settings, opt in to automatic update checks and staged apply only if you want that behavior.
2. Let Desktop stage the matching CLI and Desktop artifacts through the signed flow.
3. Quit Desktop normally when it reports that a restart is required.
4. Open the same installed Desktop app again.

At the next Desktop launch, AgentKit rereads the pending transaction, verifies the staged sizes and SHA-256 values again, and replaces the CLI and Desktop as one transaction before opening the window. Temporary backups are removed after a successful commit. There is no retained user-facing rollback copy afterward.

You can also drive the paired flow from the CLI. On Windows this stages the artifacts and launches the handoff helper instead of replacing Desktop in-process:

ak self-update --include-desktop --yes

Restart Desktop to complete the staged transaction. See the ak self-update reference for manager ownership, dry-run, output, and exit behavior.

Recover a staged update

If verification or replacement fails:

1. Do not delete the pending file, staged directory, or temporary backup named in the error.
2. Keep the currently working CLI and Desktop installation in place.
3. Correct ordinary causes such as insufficient disk space, file permissions, or another process holding the executable.
4. Reopen the same Desktop app to retry the still-verified pending transaction.

If a later replacement step fails, AgentKit attempts to restore both installed binaries. When restoration succeeds, it retains the pending transaction for a retry. If the error says rollback also failed, stop and preserve every reported path; do not manually mix binaries from different versions.

On Windows, or when no pending transaction exists, use the manual verified package flow in Installation. Replacing only the Desktop package preserves AgentKit state. Never fix an update by deleting the entire AgentKit home.