Other tools and base URLs#

Any tool or SDK that lets you set its provider’s base URL can go through Lockpin. For every tool the job is the same:

  1. Change the base URL to Lockpin’s, for the provider the tool talks to.

  2. Name the task and set its budget with two request headers, if the tool can send headers.

  3. Know what a stop looks like: HTTP 402 when a call would pass the cap.

The addresses below assume Lockpin on this machine at 127.0.0.1:8787. For a team server, use its address, and use the person’s lp_... key as the tool’s API key.

Base URLs#

lockpin providers shows these for your setup, with the key variable each provider uses.

Provider

Base URL to give the tool

Key variable on the Lockpin side

Meta

http://127.0.0.1:8787/v1

MODEL_API_KEY

OpenAI

http://127.0.0.1:8787/openai/v1

OPENAI_API_KEY

Anthropic

http://127.0.0.1:8787/anthropic (the SDK adds /v1/messages)

ANTHROPIC_API_KEY

Gemini, xAI, DeepSeek, Mistral, Groq, Together, Fireworks, OpenRouter

http://127.0.0.1:8787/<name>/v1

see lockpin providers

On your own machine, the tool keeps its own provider key and Lockpin passes it on. If the tool sends no key, Lockpin uses the key variable above from the shell that started it. On a team server, the tool’s key is the Lockpin key, and the real provider keys stay on the server.

The Gemini route takes Gemini’s OpenAI-compatible API only. For Bedrock, Vertex AI and Azure, see Supported providers.

Headers#

Header

What it does

X-Lockpin-Task: NAME

The task this call belongs to. Calls with the same name share one budget. Letters, digits, - and _ are safe, up to 128 characters.

X-Lockpin-Budget-Usd: 0.50

The task’s budget in USD. It can only lower the task’s budget. A higher value, or 0, is ignored, not refused.

X-Lockpin-Tag-<name>: value

Groups spend, for example X-Lockpin-Tag-Env: prod.

Lockpin removes every X-Lockpin-* header before the call goes to the provider. A task’s budget is a total for that name, not per day, and it keeps counting across restarts. Give a new job a new name, or raise the task in the meter. The other headers are in Budgets and tasks.

Non-streaming replies carry X-Lockpin-Cost-Usd, X-Lockpin-Spent-Usd and X-Lockpin-Remaining-Usd, and X-Lockpin-Receipt, the call’s receipt as one line of JSON. See Receipts and reports.

What a 402 looks like#

When a call would take a task past its budget, or a key past a limit, Lockpin answers before the call reaches the provider, so it costs nothing. The status is 402, and the body is in the provider’s own error shape plus a lockpin object. On an OpenAI-style route:

{"error":{"code":"budget_exceeded","message":"lockpin: task \"fix-login-bug\" 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":"fix-login-bug"}}

On the Anthropic route:

{"type":"error","error":{"type":"budget_exceeded","message":"lockpin: task \"fix-login-bug\" would exceed its $0.0001 budget: ..."},
 "lockpin":{"budget_usd":0.0001,"in_flight_usd":0,"needed_usd":0.050092,"spent_usd":0,"task":"fix-login-bug"}}

  • When a key’s limit is the one hit, lockpin also has limit, period, limit_usd and resets_at.

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

  • Lockpin reserves a call’s worst case up front: every input token uncached, plus the full output limit. So a 402 can come while the budget still shows some money left. See How the cap works.

Other statuses you may meet: 400 unknown_model (the model has no price; see Prices), 403 uncapped_call (an endpoint Lockpin cannot meter, such as embeddings), and 401 or 503 on a team server.

When a tool cannot send headers#

Put the task in the base URL. http://127.0.0.1:8787/t/<task>/anthropic or http://127.0.0.1:8787/t/<task>/openai/v1, with the task URL-escaped (claude%2Freceipt). A header wins over the path.

Run the tool under lockpin run. It sets ANTHROPIC_BASE_URL, OPENAI_BASE_URL and GOOGLE_GEMINI_BASE_URL that way for the program it starts, and names the task after the git branch, or -task NAME:

lockpin run -task nightly-refactor -- my-agent --fix-tests

A tool whose own settings name a base URL uses those instead.

Or let Lockpin name it. With neither, a call that offers tools is charged to its conversation: a task named auto- and 8 hex digits, from the conversation’s first user message, which the agent resends on every call. So each conversation gets -default-budget of its own. Two conversations that open with the same words share one. -auto-tasks=false turns this off.

Calls without tools, and every call with -auto-tasks=false, go to the task default, whose budget is a single total. Then either:

  • run with -default-budget 0 and cap each person or tool with a key that has -day, -week, -month or -total limits. This is the dependable way, because the limit lives in Lockpin and the tool cannot skip it. See Keys. On your own machine, -day-limit ($20 a day) still holds;

  • or keep a default budget that suits a single job, and change it in the meter while the job runs.

Tools without a page here#

  • Gemini CLI. Gemini CLI sends Google’s native generateContent calls through GOOGLE_GEMINI_BASE_URL, and Lockpin’s Gemini route takes the OpenAI-compatible API only, so do not count on the cap for Gemini CLI yet. With Google login, its calls do not use the base URL at all. Lockpin’s prompt review still runs as a Gemini CLI hook: lockpin hooks install -agent gemini.

  • Windsurf and Devin Desktop. Lockpin’s prompt review runs as their hook: lockpin hooks install -agent windsurf. Their model calls do not go through Lockpin.

  • GitHub Copilot. Its calls can go through Lockpin only when you use your own provider key (BYOK). Its prompt hooks cannot block, so prompt review does not run there.

Tools change quickly. If a setting here is not in your version, use a key with limits, which needs nothing from the tool.

Verify#

  • lockpin doctor lists each agent it finds on this machine and says whether its calls go through Lockpin.

  • After one call, the meter shows it under the task you named, or under an auto- or default task.