What Lockpin is#

Lockpin is a spend cap for AI agents. This page explains the problem it solves, how the cap decides each call, what runs where, and what Lockpin does not do. Read it before you install.

The problem#

An agent makes many model calls on its own, and each call costs money. Most spend controls count what was spent after the call returns, so an agent in a loop, or many calls in flight at once, can run past a limit before anything stops it.

Lockpin decides before the call is sent. It prices each call at its worst case, and refuses the call that would not fit the budget. The refused call never reaches the provider, so it costs nothing.

How it works#

Lockpin is a small program on your machine (or one server for a team). Your agent calls Lockpin instead of the provider. Lockpin changes only the address your agent calls.

agent or SDK  --->  Lockpin (127.0.0.1:8787)  --->  provider (Anthropic, OpenAI, ...)
                     |
                     +-- prices the call at its worst case
                     +-- checks it against the task's budget
                     +-- sends it, or refuses it with HTTP 402

For every call:

  1. Reserve. Lockpin holds the call’s worst-case cost: every input token uncached, plus the full output limit. Reservations make parallel calls safe: many calls at once still cannot overshoot the budget.

  2. Block or forward. If the reservation does not fit the task’s budget, the call never reaches the provider. The agent gets HTTP 402 with "code": "budget_exceeded" and the numbers. Otherwise the call goes through, streaming included.

  3. Settle. When the reply arrives, the reservation is replaced by the real cost from the provider’s usage, with cached tokens priced at the cached rate.

If the meter, VS Code or the desktop overlay is open when a call would pass its task’s budget, Lockpin holds the call for up to 3 minutes and asks: Allow this call, Raise budget or Stop. With nobody watching, or no answer in time, the agent gets the 402.

Because the worst case is reserved up front, a 402 can come while the budget still shows some money left: the next call might have cost more than that.

How the cap works covers each step in detail.

Budgets#

Limit

What it caps

Task

Calls that share a task name. A task with no budget of its own gets -default-budget, which is $1.00.

Day

Everything on this machine together per UTC day (-day-limit, default $20).

Key

One person or agent with a Lockpin key (lp_...), with daily, weekly and monthly limits.

Project

Limits under "projects" in lockpin.json.

A task’s budget is a total for that name, not per day. It keeps counting across restarts. Budgets and tasks explains how calls are grouped into tasks.

What runs where#

Part

Where it runs

What it does

The proxy (lockpin)

Your machine, or one team server

Prices, caps and forwards each call. Keeps the ledger.

The ledger

A file on the same machine

Keeps spend across restarts.

The meter

http://127.0.0.1:8787/lockpin/, served by the proxy

Shows each task’s spend against its budget, call by call.

VS Code extension

Your editor

Reads the meter you already run. The cap is still enforced by Lockpin, not by the editor.

Desktop overlay

Your desktop (Windows first)

Shows the running task’s spend and lets you answer Lockpin’s questions.

Hosted dashboard

app.lockpin.dev (optional)

Shows every machine’s spend in one place, from spend numbers only.

Your prompts and provider keys go straight from your machine to the provider. Your tools keep their own API keys: Lockpin passes each key on and never stores it. Lockpin makes no model calls of its own: all of its logic is plain arithmetic.

There is no telemetry and no automatic update check. Reporting to the hosted dashboard is off unless you turn it on, and budget decisions never wait for it. See What leaves your machine.

Providers#

Lockpin works in front of Anthropic, OpenAI, Google Gemini, Meta, xAI, DeepSeek, Mistral, Groq, Together, Fireworks and OpenRouter, and through your own cloud account on Amazon Bedrock, Google Vertex AI and Azure OpenAI. Each provider has its own base URL on Lockpin. See Supported providers.

A model with no price is refused with 400 unknown_model, so the cap cannot be skipped by accident. You can add models and prices with a catalog file. See Prices and the price feed.

What Lockpin is not#

  • Not your provider’s bill. Lockpin prices each call from its built-in catalog of list prices. lockpin reconcile compares a provider’s own usage export with what Lockpin charged.

  • Not a model or an agent. It does not call models for you or change your prompts to enforce the cap. So that the cap holds, it may give a call an output limit or, near the cap, lower one. Trimming of old tool results changes what the model sees, so it is off unless you turn it on.

  • Not a shared budget across proxies. One Lockpin process holds the ledger. Several proxies do not share budgets, so team and tag budgets across several machines are soft.

  • Not a fallback when it is down. If Lockpin is not running, your agent’s calls fail to connect. By default, when its own ledger or keys file fails, Lockpin refuses calls rather than send them unseen (-on-fault block).

  • Not a guarantee against every overspend. A call in flight when Lockpin dies was reserved in memory only, so the provider may bill it with nothing in the ledger.

Next steps#