Quickstart#

This page takes you from install to a capped agent in a few minutes: install Lockpin, point an agent at it, set a budget, see a call refused at the cap, and see your spend. It is for one person on their own machine.

Before you begin#

  • A provider API key (Anthropic or OpenAI in the examples). These steps are for API billing, where a dollar cap means something.

  • An agent or SDK that lets you set the provider’s base URL. Claude Code and Codex CLI have a one-command setup.

1. Install#

  1. Run the installer.

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

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

    The installer checks the download against the release’s SHA256SUMS, installs it for your user only, sets it up as a background service, starts it and opens the setup page.

  2. Open a new terminal and check it.

    lockpin version
lockpin doctor

Other ways to install are in Install.

2. First run#

Lockpin listens on http://127.0.0.1:8787 and serves its live meter at http://127.0.0.1:8787/lockpin/.

  1. Check that the service is running.

    lockpin service status

  2. Open the meter.

    lockpin -open

    Until your first call arrives, the meter shows a Waiting for first call card. The setup page, http://127.0.0.1:8787/lockpin/setup, gives the base URL for your provider with Copy buttons.

Your tools keep their own API keys. Lockpin passes each key on and never stores it. To have Lockpin hold a provider’s key instead, set that provider’s key variable in the shell that starts Lockpin. lockpin providers lists the names, such as OPENAI_API_KEY and ANTHROPIC_API_KEY.

3. Point an agent at it#

Pick the way that fits your agent. Lockpin changes only the address your agent calls.

lockpin connect claude

It shows the change to ~/.claude/settings.json, asks, keeps a backup, and sets ANTHROPIC_BASE_URL so every Claude Code session on this machine goes through Lockpin. Each session is its own task, with its own budget. See Claude Code.

lockpin connect codex
codex --profile lockpin

It adds a Lockpin provider and a lockpin profile to ~/.codex/config.toml, so plain codex is unchanged. See Codex CLI.

Give the tool Lockpin’s base URL for its provider:

Provider

Base URL

Anthropic

http://127.0.0.1:8787/anthropic

OpenAI

http://127.0.0.1:8787/openai/v1

Gemini (OpenAI-compatible API)

http://127.0.0.1:8787/gemini/v1

 
import anthropic
client = anthropic.Anthropic(base_url="http://127.0.0.1:8787/anthropic",
                             default_headers={"X-Lockpin-Task": "fix-login-bug",
                                              "X-Lockpin-Budget-Usd": "0.50"})

See Other tools and base URLs.

Run your agent once. The setup page turns green and the meter shows the call.

4. Set a budget#

A task with no budget of its own gets -default-budget, which is $1.00.

  1. To change it for the background service, run:

    lockpin service install -args "-default-budget 5"

    This replaces the service’s definition and keeps the new flags. To try a flag in a terminal first, run lockpin -default-budget 5.

  2. To give one task a lower budget, send two headers with its calls:

    Header

    What it does

    X-Lockpin-Task

    Names the task, so its spend is counted and capped together.

    X-Lockpin-Budget-Usd

    The task’s budget in USD. It can only lower the budget below -default-budget.

    An agent that cannot send headers can run under lockpin run, which names the task after the git branch, or -task NAME:

    lockpin run -task nightly-refactor -- codex exec "fix the tests"

Other limits: -day-limit caps everything on this machine together per UTC day (default $20), and a Lockpin key can carry daily, weekly and monthly limits for one person or agent. See Budgets and tasks.

5. See the cap#

Send one call with a budget too small for it. Before a call goes out, Lockpin reserves its worst-case cost, so this call is refused before it reaches the provider.

  1. Close the meter, and the Lockpin panel in VS Code or the overlay if you use them, so Lockpin does not hold the call to ask you.

  2. Send the call from a sh shell. It uses a new task name, cap-test, because a budget set by the header stays with that task.

    curl http://127.0.0.1:8787/openai/v1/responses      -H "Authorization: Bearer $OPENAI_API_KEY"      -H "X-Lockpin-Task: cap-test"      -H "X-Lockpin-Budget-Usd: 0.0001"      -H "Content-Type: application/json"      -d '{"model": "gpt-6.1-sol", "input": "Fix the login bug"}'

  3. Read the answer. The status is HTTP 402, in the provider’s own error shape plus a lockpin object with the numbers. Your numbers depend on the model and the input:

    {"error":{"code":"budget_exceeded","message":"lockpin: task \"cap-test\" would exceed its $0.0001 budget: spent $0.0000, in flight $0.0000, this call needs up to $0.0213","param":null,"type":"budget_exceeded"},
 "lockpin":{"budget_usd":0.0001,"in_flight_usd":0,"needed_usd":0.021315,"spent_usd":0,"task":"cap-test"}}

    Nothing was spent. The message always starts with lockpin:, so your tool’s error output shows who stopped the call.

When someone is watching (the meter, VS Code or the overlay is open), Lockpin instead holds the call for up to 3 minutes and asks there: Allow this call, Raise budget or Stop. A key, team or daily limit never asks: it refuses with the 402. See Approvals at the cap.

6. See your spend#

  • The meter. http://127.0.0.1:8787/lockpin/ shows each task’s spend against its budget, call by call, as it happens. http://127.0.0.1:8787/lockpin/#task=fix-login-bug opens it at one task.

  • VS Code. The Lockpin extension shows each task’s spend against its budget in the status bar and its side bar, and asks Lockpin’s questions there. See VS Code extension.

  • The overlay. A small island at the top of the screen (Windows first) shows the running task’s spend against its budget. See The meter and the desktop overlay.

  • The terminal. These read the ledger:

    lockpin receipt -n 5
lockpin projects
lockpin digest

    lockpin receipt shows what each of the last calls would have cost, what it cost and why. lockpin digest shows the last 7 days. If Lockpin runs as the service, run these from its data folder or pass -ledger FILE.

Verify#

  • lockpin doctor shows your agent sending its calls through Lockpin.

  • The meter lists your agent’s task with its spend against its budget.

  • The test call in step 5 got HTTP 402 with budget_exceeded.

Next steps#