Upgrade and uninstall#

This page upgrades Lockpin to a new release and removes it from a machine. Your spend history and your team’s keys are kept unless you ask to delete them.

Before you begin#

  • Know how Lockpin was installed: the one-line installer, the Windows installer with the overlay, a release archive by hand, or a fleet package (MSI, pkg, .deb or .rpm).

  • Know where your data folder is. The ledger, lockpin-ledger.jsonl, keeps your spend history:

    System

    Data folder

    Windows

    %LOCALAPPDATA%\Lockpin

    macOS

    ~/Library/Application Support/Lockpin

    Linux

    $XDG_DATA_HOME/lockpin, else ~/.local/share/lockpin

    LOCKPIN_DATA_DIR changes it.

Upgrade#

With the installer#

  1. Check what the upgrade would run.

    lockpin upgrade -dry-run

  2. Upgrade.

    lockpin upgrade

    lockpin upgrade runs the one-line installer, which downloads the latest release, checks it against the release’s SHA256SUMS and replaces the program. It keeps how Lockpin was installed: the same folder, and whether it starts at sign-in. A running Lockpin is restarted on the new version; a stopped one stays stopped.

To install a given release, pass -version:

lockpin upgrade -version v0.1.7

Running the one-line installer again does the same: it upgrades in place and restarts a running Lockpin on the new version.

The service keeps the proxy flags you gave with lockpin service install -args. They are saved in service-args.json in the data folder, so an installer upgrade does not drop them.

By hand#

  1. Replace the binary with the new release’s, after checking it against SHA256SUMS. See Install by hand.

  2. Keep the ledger and the keys file. They hold your spend history and your team’s keys.

  3. Restart the service on the new version.

    lockpin service restart

Windows installer and fleet packages#

  • The Windows installer with the overlay upgrades over an earlier install: run the new Lockpin_<version>_x64-setup.exe. It replaces lockpin.exe and keeps your history.

  • A newer MSI upgrades an older one in place. An older MSI refuses to install over a newer one.

  • On a team node, each package upgrade runs lockpin node install again with the same settings, so the node runs the new program and keeps its sealed store and keys file. See Run a team node.

Uninstall#

Installed with the one-line installer#

  1. Stop the service and remove its definition (on Windows, the Scheduled Task).

    lockpin service uninstall

  2. See what lockpin uninstall will remove.

    lockpin uninstall -dry-run

    It lists the program, the LaunchAgent or systemd user unit if one is still there, and the Windows shortcuts and PATH entry.

  3. Remove Lockpin. It lists what it will remove and asks first.

    lockpin uninstall

Your spend history and settings stay. To delete them too, add -purge:

lockpin uninstall -purge

Warning

-purge deletes your spend history and settings, including the data folder with the service’s saved flags. This cannot be undone.

Before you uninstall, consider lockpin quit. It first disconnects Claude Code and Codex, so new agent sessions go to the provider directly, then stops Lockpin. Agents still pointed at a stopped Lockpin fail to connect. To undo lockpin connect yourself:

lockpin disconnect claude
lockpin disconnect codex

Installed with the Windows installer#

Uninstall Lockpin from Settings > Apps. That removes Lockpin and the overlay, the Scheduled Task and the PATH entry, and keeps your spend history.

Installed by hand#

  1. Stop and remove the service.

    lockpin service uninstall

  2. Delete the binary.

  3. If you no longer want your spend history, delete lockpin.json, the keys file and lockpin-ledger.jsonl.

Fleet packages#

msiexec /x lockpin_<version>_windows_amd64.msi /qn

A pkg has no uninstaller of its own. Run the uninstall script:

sudo "/Library/Application Support/Lockpin/pkg/uninstall.sh"

sudo apt remove lockpin

sudo dnf remove lockpin

When a package’s settings made the machine a team node, removing the package runs lockpin node uninstall. That stops the node and removes its task or service and its copy of the program. The node’s folder (sealed store, keys file, ledger) and its account stay. A node installed by hand is left alone.

Verify#

After an upgrade:

lockpin version
lockpin doctor

lockpin version prints the version, commit and build date. lockpin doctor reports whether the service is installed and running.

After an uninstall, open a new terminal: lockpin is no longer found.

Next steps#