M7 · Settings › API & CLI tokens, agent setup, copy as CLI (wave 3)

Mockup on origin/main · v2.1.1 · default theme “Classic night” · fake data

Today before

Settings page today: earnings collection, environment, about. No API section.

Settings today (templates/settings.html:9-15): four sections, none for API access. The fleet key shows under Environment as “Fleet API Key … Not set”.

!
The only scripting key lives in the environment. CASHPILOT_ADMIN_API_KEY resolves to role owner (app/auth.py:177-179), so a Home Assistant widget or an agent gets full control, including stored credentials and volume deletion. No scopes, no expiry, no box limit, no last-used.
!
Create or rotate a key = 3 terminal steps: edit .env or the compose file, docker compose up -d, update every client. Nothing in the UI. Revoking one client means rotating everyone.
!
No schema, no CLI. OpenAPI and /docs are switched off (app/main.py:2315-2317). An agent reads app.js to learn the routes: api() is a bare fetch wrapper (app/static/js/app.js:14-38) with nothing to record or copy.
!
The Fleet card calls the enrolment key “API Key” (templates/fleet.html:138-155: “Reveal API Key”, CASHPILOT_API_KEY). People paste it into scripts; it is the worker key, role fleet (app/auth.py:180-182).
→
After: create a scoped token in 3 clicks + typing a name; revoke in 2 clicks; no restart. Copy a working CLI or curl line for anything you just did in 2 clicks.

Settings › API & CLI after 1440×900 · tokens present, one just used

Settings

Personal tokens Create token n

A token lets a script, a dashboard widget or an AI agent act as you, limited to the scopes and boxes you pick. Each one is shown once, stored hashed, and can be revoked here without a restart.

Name	Scopes	Boxes	Expires	Last used
home-assistant cp_hA2x_…f9	read	all	never	4 min ago · GET /api/earnings	Revoke
claude-code cp_Qm7d_…k2	readoperateproxies	box-abox-b	in 90 days · 6 Feb 2027	just now · POST /api/services/honeygain/restart	Revoke
old-grafana cp_Zt0p_…a1	read	all	in 3 days	19 days ago	Extend Revoke
Admin key legacy, set in .env CASHPILOT_ADMIN_API_KEY	admin (everything)	all	never	12 days ago	How to retire it

Use from a terminal

The cashpilot CLI talks to this dashboard over the same API. Every command takes --json, --dry-run on anything that changes a box, and exits non-zero on refusal.

Install, on any machine

$ uvx cashpilot --versionCopy

Or, with no install, inside the dashboard container

$ docker exec cashpilot-ui cashpilot statusCopy

$ cashpilot login --url http://cashpilot.local:8080 --token-stdinCopy

The URL above is this dashboard's own address, filled in for you. CLI reference

Use from an AI agent

Claude Code and other agents work best with a token scoped to what you want them to touch, plus the guide below. Destructive calls return a plan first; the agent must send confirm to carry it out.

Agents guide docs/agents.md llms.txt /llms.txt API schema /api/docs · signed in Claude Code skill cashpilot-operator

MCP server config

{ "mcpServers": { "cashpilot": { "command": "uvx", "args": ["cashpilot", "mcp"], "env": { "CASHPILOT_URL": "http://cashpilot.local:8080", "CASHPILOT_TOKEN": "paste the claude-code token" } } } }Copy

Or the Claude Code one-liner

$ claude mcp add cashpilot -e CASHPILOT_URL=http://cashpilot.local:8080 -- uvx cashpilot mcpCopy

Your last 10 actions as commands kept in this browser only · secrets masked

Do it once with clicks, then copy it to a script. Values from credential fields are replaced with $VARIABLE names.

10:42cashpilot service restart honeygain --box box-aCopy CLI Copy curl

10:39cashpilot egress test res-pool-1 --box box-bCopy CLI Copy curl

10:37cashpilot egress add res-pool-1 --url-stdin <<< $PROXY_URLCopy CLI Copy curl

10:31cashpilot service deploy earnapp --box box-b --env-file earnapp.envCopy CLI Copy curl

09:58cashpilot service stop storj --box box-b --yesCopy CLI Copy curl

+ 5 more · Show all · Clear

1
New “API & CLI” section in the existing settings index (templates/settings.html:9-15), owner only. g s reaches Settings today; n on this section opens Create token. Focus ring is the theme’s cyan (style.css:2253-2254).
2
Token table: scopes as chips, box allowlist, expiry with a warning 7 days ahead, last used with the last route. The env key stays visible as a legacy row so nothing breaks and the owner sees it is all-powerful. Backend: api_tokens table (hash, scopes, worker_ids, expires_at, last_used_at), checked in get_current_user next to the env keys (app/auth.py:153-183).
3
Terminal: a cli/ package published as cashpilot and also baked into the UI image, so docker exec works with no install. --token-stdin keeps the token out of shell history. Today: no CLI exists.
4
Agents: /api/docs and /openapi.json come back, but behind sign-in, which keeps the reason they were removed (app/main.py:2311-2317). docs/agents.md and a generated llms.txt list scopes, the plan then plan_id contract and exit codes. MCP server = the same CLI in mcp mode.
5
Recorder (wave 3, L5): CP.api() (app.js:14-38) appends method, path and body to a ring of 10 in sessionStorage; a route→command map turns it into CLI text. Bodies are masked by field name (password, token, *_KEY, url credentials) before storing. 2 clicks to a working command.
→
Counts. Create a read-only token for a widget: today 3 terminal steps + restart, and it is owner-level; after, 3 clicks + type a name. Revoke one client: today rotate for all; after, 2 clicks (Revoke, confirm).

Create token: dialog, keyboard flow and the four states states

Keyboard: focus starts in Name. Tab walks scopes → expiry → boxes → buttons and stays inside the dialog. Space toggles a scope, ←→ moves the expiry radio, Enter in a field submits, Esc closes and returns focus to “Create token”.

successtoken shown once

Token claude-code created. Copy it now: CashPilot stores only a hash and cannot show it again.

cp_Qm7d_N4x0VfR2sTq8LwY1bHc6ZpE3uJk2Copy

Try it

curl -s -H "Authorization: Bearer $CASHPILOT_TOKEN" \ http://cashpilot.local:8080/api/workers | jq '.[].name'Copy

Copy is focused on open, so Enter copies. On plain-http LAN origins the clipboard API is blocked; the box becomes a selected read-only field, the same fallback Fleet uses (fleet.html:150-153).

emptyfirst visit

No tokens yet. Scripts and agents use a token instead of your password.
Create token Read the agents guide

error

Could not create the token: a token named claude-code already exists. Pick another name or revoke the old one. 409

The error sits under the Name field and moves focus there, instead of a toast that disappears.

Copy as CLI everywhere you act (wave 3), and the Fleet rename after

Dashboard › service row › ⋯ menu

Honeygainbox-a$3.12⋯

Copied cashpilot service logs honeygain --box box-a

↑↓ moves, the letter jumps, Esc closes back to ⋯. Today each row has separate icon buttons and no copy (app.js:2676-2746).

Fleet › Add proxy dialog (bottom)

Collapsed by default, remembers open/closed. Same block in Deploy, Run proxied copy and Add box. Route: POST /api/proxies (fleet.html:1101).

Fleet › Add a box

CASHPILOT_UI_URL=http://cashpilot.local:8080 CASHPILOT_API_KEY=•••••••• CASHPILOT_WORKER_NAME=box-c

set~~Reveal API Key~~ → Reveal enrolment keyCopy

This key only enrols workers. For scripts and agents, create a token in Settings › API & CLI.

Rename in fleet.html:143 (and :774) and the hint at :155. The env var name stays CASHPILOT_API_KEY for compatibility; the label says what it is.

6
Admin is opt-in and red, with the exact consequence. Default scopes are read only. A box allowlist makes a token useless on other boxes (server rejects with 403 box_not_allowed).
7
Shown once, copy focused, and a curl line that proves the token works before the dialog closes.
8
One ⋯ menu per row with letter keys, carrying Copy as CLI / curl. The menu is the same keyboard pattern as M8’s dialog: focus trapped, Esc returns.
9
“Equivalent command” in every form that changes a box: the fastest way for a person to learn the CLI, and for an agent to be told “do what this form does”.
10
Rename the Fleet button so the enrolment key stops being used as an API key.

The same thing from a terminal and for an agent after

zsh — cashpilot

$ pbpaste | cashpilot login --url http://cashpilot.local:8080 --token-stdin
Signed in as token claude-code (read, operate, proxies · boxes box-a, box-b · expires 2027-02-06)
Saved to ~/.config/cashpilot/config.toml (mode 600)

$ cashpilot status --json
{
  "version": "2.2.0",
  "boxes": [
    { "name": "box-a", "online": true, "running": 6, "isolation": "on" },
    { "name": "box-b", "online": true, "running": 4, "isolation": "off" }
  ],
  "findings": [
    { "id": "down/earnapp@box-b", "severity": "fail" }
  ],
  "balance_usd": 41.87
}

$ cashpilot service restart honeygain --box box-a
✓ honeygain restarting on box-a

$ cashpilot service rm storj --box box-b
✗ refused: token claude-code lacks scope "deploy"
  Ask the owner to add it in Settings › API & CLI.
$ echo $?
3
# exit codes: 0 ok · 1 error · 2 usage · 3 auth or scope · 4 not found
#             5 refused for safety (incl. no --yes) · 6 box offline · 7 partial · 8 conflict

docs/agents.md rendered · also served as /llms.txtCopy as Markdown

Driving CashPilot from an agent

Ask the owner for a token with the smallest scopes that do the job. Never ask for admin to restart a service.

Scope	Lets you	CLI
read	status, earnings, logs, fleet	`status · service ls\|logs · finding ls`
operate	start, stop, restart	`service start\|stop\|restart`
deploy	deploy, redeploy, remove	`service deploy\|redeploy\|rm`
proxies	proxies and proxied copies	`egress add\|import\|test · copy apply`
admin	settings, credentials, tokens	`token ls\|create\|revoke · box add`

Stateful services: plan, then confirm

Storj, Mysterium and other nodes with an identity volume never lose data by default. Every remove, stop or redeploy returns a plan first:

# 1. read the plan cashpilot service rm mysterium --box box-a --dry-run --json # 2. remove, keeping the identity volume cashpilot service rm mysterium --box box-a --yes # 3. only if the owner asked: delete the volume too cashpilot service rm mysterium --box box-a --yes --delete-volume=mysterium

The volume flag must repeat the slug, the same check as the dialog in M8. Over HTTP, add dry_run=1 to the same request: it returns {"plan": …, "plan_id": "…"}; send plan_id back within 5 minutes.

Evidence on origin/main

app/auth.py:153-183
Bearer auth knows three env keys: read-only → reader, admin → owner, fleet → fleet. No per-client tokens.
app/main.py:2311-2317
docs_url=None, redoc_url=None, openapi_url=None: no schema at all, by design, because it was public.
app/static/js/app.js:14-38
api() is the single choke point for every UI call: the right place to record and translate.
app/templates/fleet.html:138-155
“Reveal API Key” and “The API key is set via CASHPILOT_API_KEY” for the worker enrolment key.
app/templates/settings.html:9-15
Settings index: Earnings collection, Credential health, Environment, About, Import. No API entry.
app/templates/fleet.html:1046-1151
Proxy routes the CLI and “Equivalent command” map onto: /api/proxies, /copies, /test.