Hosted dashboard and reporting#

The hosted dashboard at app.lockpin.dev shows every machine’s spend and refusals in one place. This page covers how machines join a team, how optional usage reporting works, exactly what it sends, and company sign-in for the dashboard. It is for team admins and IT.

Note

The dashboard is optional. The cap runs on your machines and works the same without it. With the default -report off, Lockpin sends no spend data to Lockpin.

What the dashboard shows#

Spend and refusals from every machine that reports, for signed-in members of the organisation.
Every number says when it was read (“as of”).
Each machine enforces its own cap, so a budget or total across several machines is soft: the machines together can pass it, and the dashboard labels it soft.
A dashboard budget can only lower a machine’s own limit, never raise it.

The spend cap is free on any plan. Plans change only what the dashboard keeps and who can see it. Sign up at https://app.lockpin.dev/signup.

Two separate choices#

	Joining a team	Usage reporting
Command	`lockpin enroll CODE`	`-report on` with a reporting credential
What it sends	A short status report for the team’s admins	Hourly spend totals from the local ledger
How often	Once a minute	Once a minute when there is something new
Default	Off until you enroll	Off

Joining does not turn on the usage upload.

Join a machine to your team#

Your admin gives you a code. On your own machine:

lockpin enroll CODE
lockpin enroll status

lockpin enroll status shows exactly what your admin sees. The status report never includes prompts, replies, code, file names, task names, screens or keystrokes.

Command	What it does
`lockpin enroll CODE`	Join a team with the code your admin gave you.
`lockpin enroll status`	Show exactly what your admin sees.
`lockpin enroll trust sk_...`	Accept a status key your admin reset.
`lockpin enroll leave`	Leave the team.

All four take -ledger PATH, and enroll CODE and enroll leave take -yes to skip the question.

Turn on usage reporting#

Before you begin#

A reporting credential from your dashboard admin, saved in a file (JSON with key_id and secret), or set in LOCKPIN_INGEST_TOKEN.
Lockpin runs on the machine that will report.

Steps#

See exactly what would be uploaded, before anything is sent:
```
lockpin report preview
```
-detail totals, tags or tasks previews another level.
Start Lockpin with reporting on and the credential:
```
lockpin -report on -report-token report-token.json
```
To keep it, put "report": "on" and "report-token" under "flags" in lockpin.json, or pass them in the service’s -args.
Check the reporter’s state:
```
lockpin report status
```

The reporter runs off the call path. Budget decisions never wait for it or read anything back from it, and a slow or failed upload changes no decision.

Flag	Default	What it does
`-report`	`off`	`off` or `on`.
`-report-token`	none	File containing JSON `key_id` and `secret`, or `LOCKPIN_INGEST_TOKEN`.
`-report-detail`	`tags`	The most detail this machine sends: `totals`, `tags` or `tasks`.
`-report-url`	`https://ingest.lockpin.dev`	Ingest base URL.

What reporting sends#

Each batch holds hourly totals built from the local ledger, limited to a closed list of fields, at the lower of the organisation’s level and -report-detail.

Level	What it adds
`totals`	The hour, key name (team mode), provider, model, request counts, cost, cost without cache, token counts, cache-miss counts, compaction savings, summed timings, and a pseudonymous user id when `X-Lockpin-User` is used.
`tags` (default)	Tag names and values, and a pseudonymous task id (`t-` plus 8 hex of an HMAC with the organisation’s salt).
`tasks`	The real task name.

Each batch also carries a random proxy_id made once per install (not derived from the machine, the user or any key), the Lockpin version, and the level used. Alerts send their kind, subject, period, limit, spent and reset time, never message text. A config snapshot sends key names, whether each is disabled, its dollar limits and the default task budget, never a key secret or hash.

Never sent: prompts, responses, file contents or paths, provider keys, Lockpin key secrets, webhook or Slack URLs, alert message text.

Lockpin keeps a copy of each batch as uploaded in LEDGER.report-sent.jsonl, next to the ledger, so you can see exactly what left the machine. See What leaves your machine.

Tip

IT can stop every upload on a machine, including lockpin enroll, with reporting.allowed: false in the signed policy. It does not delete what a dashboard already holds.

Keys made in the dashboard#

A machine started with -managed-keys accepts keys made in the hosted dashboard, pushed as hashes. It needs -report on and -keys. Each such key is still held to the machine’s own monthly ceiling, -managed-keys-ceiling (default 100 USD a month), whatever the dashboard set.

lockpin -keys lockpin-keys.json -report on -report-token report-token.json -managed-keys

Company sign-in#

People can sign in to the dashboard with their work account: Microsoft Entra ID, Google Workspace or Okta. This covers the hosted dashboard only. The Lockpin program on each machine never needs anyone to sign in.

An owner opens Settings, then Set up company sign-in.
Verify each email domain with a DNS TXT record at _lockpin.example.com. A domain can belong to one Lockpin organisation only.
Choose the provider: an Entra tenant ID, the Workspace’s primary domain, or your Okta domain with the app’s client ID and secret.
Choose who may join: Needs an invite (the default) or Joins automatically as a viewer.
Sign out and test it with Sign in with your company account.
Optionally turn on Require company sign-in. The page first says how many admins or viewers would lose access.

Lockpin asks the identity provider only for openid, email and profile: name, email address and a stable ID.

Owners are the break-glass. A company sign-in acts as an admin at most. Owner actions need the owner’s own emailed-code sign-in, so a problem at your identity provider cannot lock owners out. Remove a departing owner on the Members page: disabling them at your identity provider does not.
Sessions. A company sign-in lasts at most 12 hours.
Provisioning with SCIM. With SCIM 2.0 from Okta or Entra ID, someone IT deactivates is removed from the organisation as soon as the identity provider tells Lockpin: their sessions end and their machines’ Lockpin credentials are revoked. SCIM never sets roles and never touches owners. An owner makes a SCIM token (lps_...) under Provisioning (SCIM); it is shown once.
SAML, other identity providers and groups through SCIM are not available.

Audit log and exports#

Changes to members, roles, keys, sign-in, billing and export tokens are logged. Owners and admins can download the log as CSV or JSON Lines.
Owners and admins can make a read-only token that reads the audit log, spend, or both. It is shown once and only its SHA-256 hash is kept. It cannot change anything and is not a sign-in.

Data and retention#

Hourly spend is kept 35 days, and daily spend 90 days or 13 months, depending on the plan.

Verify#

Check what your admin sees for this machine:
```
lockpin enroll status
```
With reporting on, check the reporter:
```
lockpin report status
```