Budgets and tasks#

This page explains how Lockpin groups calls into tasks, how each task gets its budget, and the other limits that apply per day, per project and per key. It is for developers setting budgets on their own machine and for team leads choosing defaults.

What a task is#

A task is a name that a set of calls share. Calls with the same task name share one budget. A task’s budget is a total for that name, not per day: it keeps counting across restarts, because it is kept in the ledger. Give a new job a new name, or raise its budget in the meter.

How a call gets its task#

Lockpin takes the first of these that applies:

Source	Task name
`X-Lockpin-Task: NAME` header	`NAME`
`/t/<task>/` in the base URL (what `lockpin run` sets)	`<task>`
A Claude Code or Codex session	`claude-<id>` or `codex-<id>`, one per session (`-session-tasks`, on by default)
Any other agent call that offers tools	`auto-` and 8 hex digits of a hash of its first user message, one per conversation (`-auto-tasks`, on by default)
Anything else	`default` (in team mode, `<key name>/default`)

The header wins over the path, and the path over a Claude Code session. So with nothing set, each agent session or conversation gets -default-budget of its own instead of sharing one. Two conversations that open with the same words share an auto- task. Calls without tools stay on the default task.

In team mode, tasks are kept apart per key: alice’s fix-tests is alice/fix-tests in the meter.

Name a task#

Choose one of these, depending on what your tool can send.

With a header. Letters, digits, - and _ are safe; up to 128 characters.

X-Lockpin-Task: fix-login-bug
X-Lockpin-Budget-Usd: 0.50

In the base URL, for a tool that cannot send headers. URL-escape the task (claude%2Freceipt):

http://127.0.0.1:8787/t/fix-login-bug/anthropic
http://127.0.0.1:8787/t/fix-login-bug/openai/v1

With lockpin run. It starts the agent with ANTHROPIC_BASE_URL, OPENAI_BASE_URL and GOOGLE_GEMINI_BASE_URL pointing at Lockpin with the task (and project) in the path. The task is -task, else the git branch of this folder, else the folder’s name.

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

An agent whose own settings name a base URL (lockpin connect writes Claude Code’s) uses those instead.

Set a task’s budget#

Way	What it does
`-default-budget`	The budget, in USD, of every task that sets none. Default `1`. `0` means meter only, no cap per task.
`X-Lockpin-Budget-Usd` header	Lowers the task’s budget. A higher value, or `0`, is ignored, not refused. With `-default-budget 0`, any value sets a cap.
Edit in the meter’s Tasks table	Sets the task’s budget; `0` leaves it with no task budget.
`PUT /lockpin/api/tasks/<task>/budget`	Lowers a budget from a script.
A key’s `-task USD` (team mode)	The budget each new task of that key starts with.

Change the default where Lockpin runs. For the background service:

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.

To lower a running task’s budget from a script:

curl -X PUT -d '{"usd": 0.5}' http://127.0.0.1:8787/lockpin/api/tasks/fix-login-bug/budget

Who may raise a budget#

A raise within -allowance-pct (default 50) of the task’s budget is free, once per task per rolling 24 hours. Anyone may use it, an agent too. 0 turns it off.
A larger raise, removing a cap, and a yes at the cap beyond the allowance need the meter page. An agent’s own call is refused.
Every raise is logged as a red loosened alert, marked “within its allowance” or “not confirmed to be a person” where that applies.
A restart with a looser budget, ceiling or allowance also raises a loosened alert.

This stops a mistake or a runaway agent. An agent running as you could still edit Lockpin’s files, so it is not a guard against a determined agent with your rights.

The machine’s daily ceiling#

In solo mode, -day-limit (default 20) is the most every task and project on this machine may spend together per UTC day, in USD, whatever task a call names. 0 turns it off. Team keys have -day limits of their own instead.

Project budgets#

A call’s project is the repository its agent works in. Lockpin finds it from Claude Code’s and Codex’s working folder, lockpin run’s folder, an X-Lockpin-Project header, or /p/<project>/ in the base URL. The name is the repository folder’s name, lower-cased. Detection is on by default (-projects).

Set limits under "projects" in lockpin.json:

{
  "flags": {"default-budget": 2},
  "projects": {
    "lockpin": {"day": 10, "month": 150},
    "acme-api": {"week": 40, "folders": ["D:/clients/acme/api", "D:/clients/acme/api-v2"]},
    "*": {"day": 5}
  }
}

Each project can have day, week, month and total limits in USD, in UTC calendar periods. A missing or zero limit is no limit.
"*" gives every project not named those limits, each its own.
folders maps folders to a name, so two clones of one repository share a budget.
A project limit can only refuse calls. It never allows a call another limit would refuse.

See the spend against them:

lockpin projects

Note

A project budget is a convenience cap, not a security boundary: work from another folder is not charged to it. Use key limits when you need a boundary. Project names stay on this machine and are never uploaded.

Keys and team limits#

In team mode every call needs a Lockpin key, and each key has its own daily, weekly, monthly and total limits. For the full setup, see Person and service keys.

These key settings shape task budgets:

Setting	What it does
`lockpin keys create NAME -task USD`	Each new task of the key starts with this budget. The header can still only lower it.
`-task-cap ask`	At a task’s budget, hold the call and ask whoever watches the meter. Default for people.
`-task-cap hard`	Refuse at once, asking no one. Service keys are always `hard`.
`lockpin teams set TEAM -member-day 20`	The team’s member default: each person’s key in the team is held to the lower of this and its own limit.

lockpin keys list marks a limit that comes from the team’s member default with *, and a 402 at it names the team default. Service keys keep their own limits.

Warnings before the cap#

At 75% and 95% of a task’s budget (-task-warn-at, default 75,95), Lockpin raises an alert and adds X-Lockpin-Task-Warning to the task’s calls.
At 80% of a key, team, tag or project limit (-alert-at), it raises an alert.

See Alerts and phone approvals.

Tell the agent its budget#

An agent learns its budget only when Lockpin refuses a call. -budget-note (off by default) adds one line at the very end of each request of a task that has a budget:

[Lockpin] Budget for this task: $0.19 of $0.50 left, about 4 more calls at the current rate. If you cannot finish within that, stop calling tools, and reply with what is done and what is left.

Under a quarter of the budget left, the second sentence reads “Wrap up now: …”.
The line is a fixed template with numbers only, placed after everything the agent sent so the prompt cache still reads the agent’s own prefix.
The cap is unchanged: the call reserves for the note, so a call right at the cap can get its 402 slightly earlier.
Per request: X-Lockpin-Budget-Note: on|off. It changes what the model sees.

Verify#

Open http://127.0.0.1:8787/lockpin/ and switch to Detailed. Your task appears in the Tasks table with its budget.
Make one call and check the reply’s X-Lockpin-Remaining-Usd header, or run:
```
lockpin receipt -n 1
```