Install#

This page installs Lockpin on Windows, macOS or Linux, sets it up as a background service, and checks the setup with lockpin doctor. It is for anyone installing Lockpin on their own machine. For a shared team machine, see Run a team node.

Before you begin#

A Windows, macOS or Linux machine, Intel/AMD (amd64) or ARM (arm64).
No admin rights or sudo for the one-line installer: it installs for your user only.
Network access to lockpin.dev and github.com. Behind a company proxy, see Corporate proxies and custom CAs.

Install with one line#

Run the installer.

Windows

In PowerShell:

irm https://lockpin.dev/install.ps1 | iex

macOS and Linux

curl --proto '=https' --tlsv1.2 -fsSL https://lockpin.dev/install.sh | sh

Open a new terminal. The installer changes your PATH, which a terminal reads when it starts.
Check the install.
```
lockpin version
lockpin doctor
```

The download comes from the public releases at github.com/Lockpin/lockpin. No GitHub sign-in is needed.

What the installer does#

Picks the build for your machine (Intel/AMD or ARM) and checks it against the release’s SHA256SUMS. A download that does not match is refused.
Installs it for your user only, with no admin rights or sudo.
Adds Lockpin to the Start menu (Windows).
Runs lockpin service install, so Lockpin starts when you sign in, restarts if it stops, and writes its output to one log.
Starts Lockpin now and opens the setup page.

The setup page, http://127.0.0.1:8787/lockpin/setup, gives the base URL for your provider with Copy buttons, and code for Python, Node.js, curl or environment variables. It turns green when the first call arrives.

Installer options#

Set these before you run the installer.

Variable	What it does
`LOCKPIN_NO_SERVICE=1`	Skip the service, so Lockpin does not start at sign-in. `LOCKPIN_NO_AUTOSTART=1` does the same.
`LOCKPIN_NO_START=1`	Install without starting Lockpin now.
`LOCKPIN_VERSION`	Install a given release.
`LOCKPIN_NO_LINGER=1`	Linux with no desktop (a server over SSH): do not keep Lockpin running after you log out.
`LOCKPIN_SCAN_ONLY=1`	Install nothing. See Scan before you install.

Scan before you install#

With LOCKPIN_SCAN_ONLY, the installer downloads and checks Lockpin the same way, runs lockpin waste-scan on your Claude Code logs from a temporary folder, prints the result and removes it. It prints what the last 30 days of calls cost at API list prices, and what Lockpin’s cache options would have saved. Nothing is installed, started or changed, and the logs never leave the machine.

Windows

$env:LOCKPIN_SCAN_ONLY = '1'; irm https://lockpin.dev/install.ps1 | iex

The setting lasts for that PowerShell window. Run Remove-Item Env:LOCKPIN_SCAN_ONLY before you install from it.

macOS and Linux

curl --proto '=https' --tlsv1.2 -fsSL https://lockpin.dev/install.sh | LOCKPIN_SCAN_ONLY=1 sh

Windows installer with the overlay#

On Windows you can install Lockpin with one installer instead of install.ps1: Lockpin_<version>_x64-setup.exe. It installs Lockpin and the desktop overlay, the small island that shows a task’s spend and asks Lockpin’s questions, with its tray icon.

It uses the same folder as install.ps1, %LOCALAPPDATA%\Programs\Lockpin, and the same Scheduled Task, PATH entry and data folder (%LOCALAPPDATA%\Lockpin). You can run it over an install.ps1 install; it keeps your history.
Both start at every sign-in, each from its own Scheduled Task: Lockpin for the proxy and Lockpin Overlay for the overlay.
The Start menu entry Lockpin opens the overlay. lockpin -open still opens the meter.
IT can run it silently with /S in each user’s session.

Warning

Releases are not code-signed yet, so Windows SmartScreen warns about the installer. Check its SHA-256 against the .sha256 file next to it first.

Keep it running#

lockpin service keeps Lockpin running in the background: it starts when you sign in, starts again when it stops on an error, and writes its output to one log file. Nothing needs admin rights or sudo. The installer runs it for you. After a manual install, run it yourself:

lockpin service install

Every subcommand prints what it is about to write and run and asks first. -yes skips the question and -dry-run only prints.

System	What `install` writes	Log
Windows	A per-user Scheduled Task named `Lockpin`, run at sign-in and restarted on failure.	`%LOCALAPPDATA%\Lockpin\lockpin.log`
macOS	A LaunchAgent, `~/Library/LaunchAgents/dev.lockpin.plist`, with `RunAtLoad` and `KeepAlive`.	`~/Library/Logs/Lockpin/lockpin.log`
Linux	A systemd user unit, `~/.config/systemd/user/lockpin.service`, with `Restart=on-failure`.	`journalctl --user -u lockpin`

On a Linux server over SSH, a user unit stops when your last session ends. loginctl enable-linger $USER keeps it running; the installer does this for you unless LOCKPIN_NO_LINGER=1.

Other service commands:

lockpin service status
lockpin service start
lockpin service stop
lockpin service restart
lockpin service install -args "-default-budget 5"

-args stores proxy flags in the service definition. install replaces an existing definition, so run it again to change them. Without -args, it keeps the flags you gave before. -args "" clears them.

Install by hand#

Every release has six archives (Windows, macOS and Linux, each for amd64 and arm64) and a SHA256SUMS file. Pick amd64 for Intel and AMD processors and arm64 for Apple silicon and other ARM machines. uname -m prints x86_64 or arm64/aarch64. On Windows, Settings, System, About shows the processor.

The binaries are not code-signed, so Windows SmartScreen and macOS Gatekeeper may warn about them. Check each download against SHA256SUMS first.

Download the archive for your machine and SHA256SUMS from the releases page.

Check the download, unpack it and put it on your PATH. Replace 0.1.0 and the architecture with yours.

Windows

In PowerShell, in the folder you downloaded to. The two hashes must be identical.

(Get-FileHash .\lockpin_0.1.0_windows_amd64.zip -Algorithm SHA256).Hash.ToLower()
Select-String lockpin_0.1.0_windows_amd64.zip .\SHA256SUMS
Expand-Archive .\lockpin_0.1.0_windows_amd64.zip -DestinationPath $env:LOCALAPPDATA\Programs
$bin = "$env:LOCALAPPDATA\Programs\lockpin_0.1.0_windows_amd64"
[Environment]::SetEnvironmentVariable("Path", "$([Environment]::GetEnvironmentVariable('Path','User'));$bin", "User")

Open a new PowerShell window. If Windows says it “protected your PC” the first time, the file is unsigned: choose More info, then Run anyway, or unblock it once with Unblock-File "$bin\lockpin.exe".

macOS

shasum -a 256 lockpin_0.1.0_darwin_arm64.tar.gz
grep darwin_arm64 SHA256SUMS
tar -xzf lockpin_0.1.0_darwin_arm64.tar.gz
sudo install -m 755 lockpin_0.1.0_darwin_arm64/lockpin /usr/local/bin/lockpin
sudo xattr -d com.apple.quarantine /usr/local/bin/lockpin 2>/dev/null || true

The xattr line clears the quarantine mark macOS puts on a file downloaded in a browser. Without sudo, copy the program to ~/.local/bin instead, and make sure that folder is on your PATH.

Linux

sha256sum -c --ignore-missing SHA256SUMS
tar -xzf lockpin_0.1.0_linux_amd64.tar.gz
sudo install -m 755 lockpin_0.1.0_linux_amd64/lockpin /usr/local/bin/lockpin

The binary is static (no libc needed), so it runs on any distribution of the right architecture, including Alpine.

Check the version.
```
lockpin version
```
Write a config file, check it, and run Lockpin.
```
lockpin init
lockpin doctor -config lockpin.json
lockpin -config lockpin.json
```
lockpin init asks which providers you use and whether it is for one person or a team. It never asks for a provider key and never prints one. To skip the questions, run lockpin init -yes -providers openai,anthropic.
Optional: run lockpin service install so Lockpin starts at sign-in.

Packages for a fleet#

For many machines at once there are packages for the tools companies already use: an MSI for Windows (Intune or msiexec), a pkg for macOS (Jamf, Kandji), and a .deb and an .rpm for Linux (apt, dnf, Ansible). They are unsigned for now. The winget, Scoop and Homebrew listings are not published yet.

Windows (MSI)

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

The MSI installs for the whole machine, in C:\Program Files\Lockpin, with that folder on the system PATH. It does not install the overlay or start Lockpin at each sign-in.

macOS (pkg)

The pkg installs the program in /Library/Application Support/Lockpin/pkg and links /usr/local/bin/lockpin to it when nothing is there. Until it is signed and notarised, Gatekeeper blocks it when opened by hand.

Linux (.deb and .rpm)

sudo apt install ./lockpin_<version>-1_amd64.deb

sudo dnf install ./lockpin-<version>-1.x86_64.rpm

They install /usr/bin/lockpin. apt and dnf repositories are not set up yet: install the files.

Each package can also make the machine a team node. See Run a team node.

Verify#

Run lockpin doctor:

lockpin doctor

It prints a pass/fail list for the whole chain, each line with the fix when it fails:

the price catalog is valid, and how old its prices are;
the port is free or held by a running Lockpin, and a Lockpin answers there;
the service is installed and running, with its pid and log;
the ledger can be written;
each chosen provider’s key variable is set (it says set or not set, never the value);
each agent on this machine (Claude Code, Codex, Cursor, Gemini CLI, Windsurf) sends its calls through Lockpin or does not, and which of Lockpin’s hooks it has;
where a test call to each provider would go.

Add -network to also send one HEAD request, with no credentials, to each provider’s host. It makes no model calls.

Then open the meter:

lockpin -open

Until your first call arrives, the meter shows a Waiting for first call card.

If lockpin is not found, open a new terminal. For other problems, see Troubleshooting.

Next steps#

Quickstart: point an agent at Lockpin and see the cap.
Connect an agent: the exact setting for your tool.
Upgrade and uninstall.