Set up a team#

Run one Lockpin on a shared machine for a whole team, so each person and each automated job gets its own key and limits and nobody else holds the provider key. This page is for the team lead or admin who sets up the server.

How team mode works#

In team mode, one Lockpin holds the team’s provider keys. Every call must carry a Lockpin key (lp_...) from a keys file. Each key has its own daily, weekly, monthly or total limit, and a call reserves its worst case against the task’s budget and every limit above it at once. A leaked key can be switched off alone.

Limits and allowed AI are set at three levels. Each level can only narrow the one above it:

Level	What it holds	Set with
Workspace	The whole organisation on this server: outer limits and allowed providers and models	`lockpin workspace set`
Team	A budget its keys share, its allowed AI, and a member default	`lockpin teams create`, `lockpin teams set`
Key	One person’s or one job’s limits and allowed AI	`lockpin keys create`, `lockpin keys set`

An edit that would widen past the level above is refused with the reason. A call outside a level’s allowed AI gets 403 with refused_by naming the level. A call over a team’s budget gets 402 naming the team.

Roles#

Role	What it may do
`owner`	One per workspace. Everything. Making someone else owner makes you an admin.
`admin`	Every team and every key.
`lead`	The members of their own team.
`member`	The default. Uses AI within its limits.

Before you begin#

Lockpin is installed on the shared machine. See Install.
You have the provider keys for the providers the team uses. They stay on the server, in its environment, or sealed on a team node.
You know the address members will use to reach the server. Across offices, put Lockpin behind a reverse proxy with HTTPS and use that address.

Tip

For a shared machine where the provider keys must be sealed and the program protected from the people who use it, run a team node instead. Everything on this page also works on a node.

Set up the server#

Write the configuration and a keys file with a first key. lockpin init asks about anything you do not pass as a flag:
```
lockpin init -mode team -key-name alice -yes -providers openai
```
It prints the first key’s lp_... secret once. Give it to that person; it cannot be shown again.

Set the workspace’s name and outer limits:

lockpin workspace set -name Acme -kind business -providers openai,anthropic -month 2000

Create a team with a budget its keys share:

lockpin teams create backend -providers openai -day 100

Set the team’s member default, the most each person’s key in the team may spend:
```
lockpin teams set backend -member-day 20
```

Add people. Either make an invite link, which makes one key when someone opens it:

lockpin invites create -url http://10.0.0.5:8787 -team backend

or make a key yourself and hand it over:

lockpin keys create bob -team backend -role member -day 40

Set the provider key in the shell that starts Lockpin, then start it with the configuration lockpin init wrote:
Windows
$env:OPENAI_API_KEY = "..." lockpin -config lockpin.json -listen 0.0.0.0:8787
macOS and Linux
export OPENAI_API_KEY=... lockpin -config lockpin.json -listen 0.0.0.0:8787
lockpin providers lists the key variable for each provider. A running Lockpin picks up changes to the keys file within a second, with no restart.
Give each member the server’s base URL and their key. They set their client’s API key to their lp_... key and the base URL to the server’s address, for example http://SERVER:8787/v1. Everything else works as before.

Important

The meter and its admin API (/lockpin/) have no login, so in team mode they answer only on the server itself. If you put a reverse proxy in front, forward only the API paths (/v1/ and /<provider>/v1/) and nothing under /lockpin/. To look at the meter from your laptop, use an SSH tunnel: ssh -L 8787:127.0.0.1:8787 server, then open http://127.0.0.1:8787/lockpin/. Admins on other computers can use the remote admin channel.

Teams and member defaults#

lockpin teams manages teams. Limits are in USD per UTC calendar day, week (from Monday), month, or in total.

lockpin teams list
lockpin teams create NAME [limits] [-providers LIST] [-models LIST]
lockpin teams set NAME [limits] [-providers LIST] [-models LIST] [-member-day USD] [-member-week USD]
                  [-member-month USD] [-member-total USD]
lockpin teams delete NAME

Flag	What it does
`-day`, `-week`, `-month`, `-total`	The team’s budget, shared by its keys. `0` removes one.
`-providers`, `-models`	What the team allows. A team cannot allow a provider the workspace does not.
`-member-day`, `-member-week`, `-member-month`, `-member-total`	The member default. Each person’s key in the team is held to the lower of this and its own limit. It cannot be above the team’s own limit for the same period. Service keys keep their own.

lockpin keys list marks a limit that comes from the member default with *, and a 402 at that limit names the team default. lockpin teams delete works only once the team has no keys.

To move an existing key into a team:

lockpin keys set alice -team backend -role member

Team budgets across machines are soft#

A team budget is exact on the one Lockpin that holds the keys file: every call made with the team’s keys goes through its ledger. A team or tag budget that spans several machines is soft. Each machine enforces it against its own ledger, so the machines together can spend more than the budget. The hosted dashboard labels such budgets soft.

Invites#

An invite is a link, and a QR code of it, that makes one key in a team when it is opened. The new member chooses a name and gets their key and their tools’ base URLs on the spot. They install nothing.

lockpin invites list
lockpin invites create -url ADDRESS [-team TEAM] [-role member|lead] [-days N]
lockpin invites revoke ID

Flag	Default	What it does
`-url`	none	How members reach this server, such as `http://10.0.0.5:8787`.
`-team`	none	The team the new key joins.
`-role`	none	`member` or `lead`.
`-days`	`7`	How long the invite lasts, at most 30.

An invite works once, expires, and can be revoked. The command prints the link and a QR code in the terminal.
Only the invite’s SHA-256 hash is stored, so the link is shown only when it is made.
The token is after # in the link, so the browser never sends it in an address, a log line or a Referer.
Joining is limited to 20 tries per address per 10 minutes.
A key made from an invite lives 180 days, like one made with lockpin keys create.

You can also make and list invites in the meter’s Teams panel.

Pages for leads and members#

Team leads manage their team at /lockpin/team on the address members use, signed in with their own key. They see their team’s keys and spend, invite members, narrow a member’s allowed AI and limits (never past the team’s), disable or enable a member, and cancel invites. Admins and the owner can use the page for every team.
Members see their own spend, limits, allowed AI, base URLs and team lead at /lockpin/me.
Nobody can change their own key, and only the owner can change an admin.

Audit#

Every change to keys, teams and the workspace, from the command line or the meter, is kept in the keys file (the last 500) with who made it, and shown in the meter’s Audit panel. Back up the keys file and the ledger. The keys file holds only hashes of the keys, so a lost secret means lockpin keys rotate, not recovery.

Optional: kept prompts#

Kept prompts are off by default. -keep-prompts 30 keeps the last prompt each person types, for 30 days, on the team server only. Only the turn a person typed is kept, at most 8 KB of it. Admins read them in the meter’s Prompts panel, and each member sees their own on /lockpin/me with a notice that they are kept. Nothing about them is uploaded.

Warning

Recording what staff type can be workplace monitoring. Tell your team first, and check the rules where they work.

Join a machine to your team’s dashboard#

If your team uses the hosted dashboard, a member joins their own machine with the code their admin gave them:

lockpin enroll CODE
lockpin enroll status

Joining shares a short status report with the team’s admins once a minute. It never includes prompts, replies, code, file names, task names, screens or keystrokes, and it does not turn on the usage upload. lockpin enroll status shows exactly what the admin sees. lockpin enroll leave leaves the team.

Verify#

List what you set up:

lockpin workspace show
lockpin teams list
lockpin keys list

Check the whole chain, including the keys file:
```
lockpin doctor -keys lockpin-keys.json
```
Make one call with a member’s key. The reply carries X-Lockpin-Key-Remaining-Usd and X-Lockpin-Key-Resets.