Quickstart
PyxGrant needs Node 22.13 or newer. It stores state in one SQLite file under data/.
npm install npm run build npm start # PyxGrant control plane http://127.0.0.1:8787
Open http://127.0.0.1:8787 for the command center. The first boot seeds Northstar Health, a fictional demo organization, so there are real denies to look at.
ALIDADE_BREAK_GLASS to a secret of at least 20 characters, and each use is recorded. Change the demo passwords before the host is shared.Decide API
Sign in, then post a request. Operators and developers can call decide. The response is the signed record.
curl -c jar -X POST http://127.0.0.1:8787/api/login \
-H 'content-type: application/json' \
-d '{"email":"[email protected]","password":"<personal password>"}'
curl -b jar -X POST http://127.0.0.1:8787/api/decide \
-H 'content-type: application/json' \
-d '{
"agentId": "cursor-sam",
"action": "tool.invoke",
"toolId": "shell.exec",
"toolHash": "<pinned hash>",
"command": "npm test",
"workspacePath": "/work/northstar",
"forecastCents": 2
}'
| Field | Meaning |
|---|---|
action | tool.invoke, tool.result, llm.complete, a2a.hop, file.read, file.write, file.download, egress, browser.act, payment.capture, audio.ingest, spawn, memory.write, admin |
toolHash | Must equal the pinned hash of the tool's id and description, or the call is denied with R-HASH. |
listDigest | Digest of the tools/list the agent saw. It is compared with the catalog pin on the plane. |
runId, runBudgetCents | Share one budget across every process in a run. The first limit sticks. |
approvalGrant | A grant id. It only applies when the grant's argument hash matches this request. |
observedHash, observerPublic, observationSig | Independent readback. Required for payments and irreversible tools. The observer key must differ from the appliance key. |
Verdicts
| Verdict | What the checkpoint does |
|---|---|
| ALLOW | Forward the call. |
| MODIFY | Forward the rewritten call, for example with emails redacted or SELECT columns masked. |
| DEGRADE | Forward to the cheaper model named in the record. |
| ESCALATE | Hold for an approver who does not own the agent. |
| RATE_LIMIT | Refuse for now. |
| QUARANTINE | Hold the content. It does not reach the model or memory. |
| DENY | Refuse. |
| KILL | Refuse and stop the agent. |
CLI checkpoint
Wrap a shell command. The exit code is 0 for allow, modify, or degrade, 1 for a refusal, and 3 when the decision point cannot be reached.
npm run pep -- decide --agent cursor-sam --tool shell.exec --command "npm test" \ --email [email protected] --password "<personal password>"
MCP guard
Run an MCP server behind the guard. Denied tools/call requests get JSON-RPC error -32001 and are not forwarded. Server output that carries injection or a secret is withheld from the agent.
npm run collect -- proxy --token <device token> --agent cursor-sam -- node my-mcp-server.js
Collector
The collector checks known locations for Cursor, Claude Code, Copilot, and MCP config, plus running process names. It does not walk the disk. Secret excerpts are stripped before anything is sent.
npm run collect # scan this machine npm run collect -- --root ./repo # scan one folder npm run collect -- --ci # exit 1 on a secret or autoconnect
FinOps
Every record carries forecast, debited, and avoided cost in nine buckets. GET /api/money returns wallets, run ledgers, and showback. GET /api/export/focus and GET /api/export/gl return CSV files.
Verify a receipt
Get the public key through a channel you trust, then check the record. The record does not contain the key.
curl -b jar http://127.0.0.1:8787/api/keys/verify
curl -b jar -X POST http://127.0.0.1:8787/api/verify \
-H 'content-type: application/json' \
-d '{"record": { ... }, "publicKey": "-----BEGIN PUBLIC KEY-----..."}'
# {"ok": true}
Coverage map
The command center's assurance tab maps rules to OWASP LLM Top 10, OWASP agentic risks, MCP risks, and MITRE ATLAS techniques. A few examples:
| Risk | Rule | Evidence |
|---|---|---|
| MCP tool poisoning | R-HASH | Pin mismatch on the record |
| Supply chain drift | R-DRIFT, R-LIST | Digest mismatch |
| Excessive agency | R-IRREVERSIBLE, R-READBACK | Approval and observer signature |
| Sensitive data disclosure | R-SLACK, R-PHI-BAA | Session taint on the record |
| Unbounded consumption | R-LOOP, R-RUN | Wallet and run ledger |