passcontrol 0.9.5 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,20 +1,216 @@
1
1
  # PassControl
2
2
 
3
- PassControl is an identity and credential gateway for AI agents. It keeps
4
- provider API keys out of agent configuration and applies per-agent scopes, policies,
5
- budgets, and stop controls before forwarding model requests.
3
+ **An identity and credential gateway for AI agents.** The agent never holds the real
4
+ provider key: PassControl authenticates it, checks scope, policy and budget, then injects
5
+ the key and forwards the request. Call logs and signed receipts let you inspect what
6
+ happened, with [explicit limits on that evidence](#limits-and-security-status).
6
7
 
7
- Bring your own provider key. In **Cloud**, it is stored in the managed server-side
8
- Supabase Vault. When **self-hosted**, you operate the gateway, Vault, database, and
9
- Redis. In both cases the gateway decrypts and injects the provider key; the agent
10
- receives the provider response, not that key. The gateway operator remains trusted:
11
- this is credential isolation, not end-to-end encryption from the agent to the provider.
8
+ Use it when you want to give each agent its own permissions, spending allowance and
9
+ stop control without copying provider secrets into every tool. Bring your own provider key.
12
10
 
13
- Built by one developer under [Vertias](https://vertias.eu). Early software, **not yet
14
- independently audited**. Start with a non-critical provider key. Source-available
15
- under [BSL 1.1](./LICENSE).
11
+ | Start here | Choose it when | You operate |
12
+ |---|---|---|
13
+ | [Cloud](#cloud) — free private beta, access by request | You want a managed gateway without running a database or Docker | Your agents and provider account |
14
+ | [Self-host](#self-host) — full working core | You want the gateway and provider credentials on infrastructure you control | Gateway, dashboard, Supabase Auth + Vault + database, and Redis |
15
+
16
+ A **Passport** is an Ed25519 signing key used to obtain a short-lived visa. A **Direct
17
+ Agent Key** is a lower-assurance bearer credential bound to one agent; its calls are
18
+ not passport-signed. Both go through gateway controls.
19
+
20
+ Built by one developer under [Vertias](https://vertias.eu). Early software, **not
21
+ independently audited**. Start with a non-critical provider key. Source-available under
22
+ [BSL 1.1](./LICENSE).
23
+
24
+ ## Cloud
25
+
26
+ [Request beta access](https://passcontrol.vertias.eu/beta). To look around first, try
27
+ [the keyless browser demo](https://passcontrol.vertias.eu): it synthesizes output and
28
+ does not call a billed provider.
29
+
30
+ Once you have access, install the CLI with Node/npm and sign in:
31
+
32
+ ```sh
33
+ npm install -g passcontrol
34
+ passcontrol login
35
+ ```
36
+
37
+ Approve only the device code from your own terminal: this grants the machine a workspace
38
+ control key. Login creates a Passport locally, registers its public key, and attempts a
39
+ keyless governed call and receipt verification. That check needs demo and signing enabled;
40
+ it is not a real-provider test.
41
+
42
+ For a real call, add a provider key in the dashboard, give the agent a matching
43
+ provider/model scope and budgets, and follow [the first-call tutorial](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md).
44
+ For a static-key client, use **Connect an agent** and copy its generated gateway URL,
45
+ Direct Agent Key and concrete model into your client. The provider key stays in Vault.
46
+
47
+ ## Self-host
48
+
49
+ Already stuck? See [self-host troubleshooting and operations](https://github.com/Vertias3u/PassControl/blob/main/docs/self-host.md).
50
+
51
+ Use **Node 22+**, npm, Git, Docker and the Supabase CLI. The npm package contains the CLI
52
+ and compiled SDK; setup obtains the public application source and starts the local stack.
53
+
54
+ ```sh
55
+ npm install -g passcontrol
56
+ passcontrol setup
57
+ ```
58
+
59
+ Setup starts Supabase (Postgres + Auth + Vault) and Redis with a REST adapter, applies
60
+ migrations, seeds a local account and opens the dashboard. There are no shared default
61
+ credentials. This is a **local development setup**, not a production deployment.
62
+
63
+ **Updating.** `passcontrol update` updates the CLI and the checkout `setup` made. It shows the
64
+ plan first (`--check` stops there), asks once (`--yes` for scripts), then updates an npm global
65
+ install of the CLI to the exact version it found and lets the new CLI finish. For the app it
66
+ fast-forwards to the public repo's `main`, runs `npm ci`, applies new migrations (listed in the
67
+ plan; they only go forward), and restarts the dashboard if it was running. It leaves a checkout
68
+ alone, and says why, if it has local changes, has diverged, is not a clone of the public repo,
69
+ or was moved since setup (re-running the stack there would start an empty database). npx, pnpm,
70
+ yarn, bun and volta installs get the right command printed instead. If an update stops part way,
71
+ `passcontrol update --app-only` finishes it.
72
+
73
+ 1. **Make a Passport call.** Add a non-critical provider key in **Provider Keys**. Issue a
74
+ Passport with a matching provider/model scope and budgets. Choose the dashboard's
75
+ Sidecar or MCP configuration flow, copy its generated Passport import command into
76
+ your terminal, then paste the one-time secret at the hidden prompt. The command itself
77
+ contains no secret. Follow the generated client configuration and send a small prompt.
78
+ Check the call and budget charge in the dashboard.
79
+ 2. **Try a Direct Agent Key.** Use **Connect an agent**, select a concrete model within
80
+ scope, and copy the generated gateway URL and reveal-once key into your static-key
81
+ client. Send another prompt and check its authentication method in the call log.
82
+ 3. **Check the budget.** Lower the test agent's token budget below the next request's
83
+ reservation estimate and retry; expect a budget refusal. Restore the budget afterward.
84
+ 4. **Check the kill switch.** Arm it in the dashboard and retry; subsequent requests
85
+ should be refused. Disarm it when finished. It cannot cancel a request already upstream.
86
+
87
+ The Passport import hands browser-issued configuration to the CLI without putting its
88
+ secret in shell history. Keep the one-time secret until import succeeds.
89
+ [The tutorial](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md) explains the manual
90
+ CLI path; [client options](#connect-a-real-agent) cover SDK, Sidecar and MCP.
91
+
92
+ ## Limits and security status
93
+
94
+ PassControl is **not independently audited**. The public developer API has **not shipped**;
95
+ the source includes a control-plane API, but that is not a launched public developer service.
96
+ No independent audit or production assurance is implied by the test suite.
16
97
 
17
- ## Request and authentication flow
98
+ PassControl governs requests routed through it. It cannot prevent an agent from using
99
+ another credential or network path, secure a compromised signer, guarantee a provider's
100
+ usage report, or make an issuer's assertions independently true. Budget admission reserves
101
+ an estimate, not a guaranteed invoice ceiling. Logging and receipt signing are best-effort;
102
+ a valid receipt does not prove every call was recorded.
103
+
104
+ The gateway operator remains trusted: Cloud uses managed server-side Supabase Vault;
105
+ self-hosting uses your Vault. The gateway decrypts and injects the provider key. This is
106
+ credential isolation, not end-to-end encryption from agent to provider.
107
+
108
+ Short visas, stop controls, pricing tables and evidence each have further limits below.
109
+ Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/Vertias3u/PassControl/security/advisories/new).
110
+ See [SECURITY.md](https://github.com/Vertias3u/PassControl/blob/main/SECURITY.md) and [LICENSE](./LICENSE) for security guidance and usage terms.
111
+
112
+ ## Connect a real agent
113
+
114
+ Use the dashboard's generated provider-native configuration: gateway base URL, Direct
115
+ Agent Key and model. Anthropic uses its native base URL and key variables. Never paste
116
+ a Passport private key into an API-key field.
117
+
118
+ To see the whole integration run once, [`examples/direct-key-worker.mjs`](https://github.com/Vertias3u/PassControl/blob/main/examples/direct-key-worker.mjs)
119
+ is an ordinary OpenAI-SDK worker configured only by the agent's Setup file
120
+ (`passcontrol.env`). It makes one governed call and prints its receipt ID, then asks for a
121
+ model outside the agent's access and shows PassControl refusing it before the provider.
122
+
123
+ Add a provider credential in the dashboard and give the agent a concrete model within
124
+ its scope and suitable budgets. Choose by what your client supports:
125
+
126
+ | Client | Integration |
127
+ |---|---|
128
+ | Static base URL + API key | Dashboard **Connect an agent**: copy its provider-native URL and DAK |
129
+ | Your JS/TS code | `PassControl` from `passcontrol/sdk`; [SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md) |
130
+ | Static-key client needing Passport | `passcontrol sidecar`, then `passcontrol env <integration>` |
131
+ | MCP client | `passcontrol mcp`; configure as below |
132
+
133
+ Direct Agent Keys point the client at the PassControl gateway origin. Passport Sidecar clients
134
+ point at loopback with a provider path (for example `http://127.0.0.1:8788/api/v1/anthropic`) and the sidecar forwards to the gateway.
135
+ The sidecar adds per-request sender proof; the current SDK and MCP paths use bearer visas and are
136
+ refused when sender proof is required.
137
+
138
+ For a Passport bridge to Cloud or self-host, start this in one terminal:
139
+
140
+ ```sh
141
+ passcontrol sidecar
142
+ ```
143
+
144
+ In another terminal, print the client settings:
145
+
146
+ ```sh
147
+ passcontrol env hermes
148
+ ```
149
+
150
+ For MCP, write client configuration using the global Passport profile, with no secret
151
+ in the generated configuration:
152
+
153
+ ```sh
154
+ passcontrol configure claude-desktop --write
155
+ ```
156
+
157
+ The cursor preset also writes configuration; claude-code prints its client-managed add command.
158
+
159
+ The sidecar listens on loopback by default and substitutes a visa for the client's dummy
160
+ API key. Treat access to that local listener as access to the configured agent. It is
161
+ not a sandbox against other processes running as you. Its provider CONNECT requests are
162
+ refused; use base URLs rather than TLS interception.
163
+
164
+ Presets (from `cli/presets.mjs`): `generic`, `openhands`, `litellm`, `aider`, `hermes`, `cline`, `continue`, `chatbox`, `jan`, `msty`, `cherry-studio`, `open-webui`, `librechat`; service presets: `github`, `telegram`; MCP presets: `claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
165
+ supported paths. [Hermes configuration](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
166
+
167
+ ## CLI configuration and key storage
168
+
169
+ <details>
170
+ <summary>Command browser, key custody and Passport import</summary>
171
+
172
+ Run **`passcontrol`** with no arguments in an interactive terminal to open the command
173
+ browser: searchable grouped commands, recent actions, and configuration-aware options.
174
+ Use `passcontrol --help` or explicit commands in scripts.
175
+
176
+ The direct CLI call uses off/observe sender-proof mode; real provider calls need a stored
177
+ key and matching scope. Key migration moves an existing file key to the OS store.
178
+
179
+ ```sh
180
+ passcontrol status
181
+ passcontrol call "Say hello"
182
+ passcontrol doctor --deep
183
+ passcontrol key status
184
+ passcontrol key migrate
185
+ passcontrol logout
186
+ ```
187
+
188
+ The CLI supports macOS Keychain, Linux Secret Service (`secret-tool`), and Windows
189
+ DPAPI-backed storage. File configuration may contain a storage marker instead of the
190
+ Passport secret; explicit environment secrets take precedence. An unavailable OS store
191
+ can use an existing file fallback with a warning. Custody shown by the gateway is
192
+ **DECLARED evidence**, not proof of storage. The signer still reads key material into
193
+ process memory; this is not a non-exportable hardware key.
194
+
195
+ For a Passport issued in the dashboard for Sidecar or MCP, import it without putting the
196
+ one-time secret in shell history:
197
+
198
+ ```bash
199
+ passcontrol passport import --global --gateway https://YOUR-PASSCONTROL-HOST --id PUBLIC_PASSPORT_ID
200
+ ```
201
+
202
+ The CLI proves the 32-byte Ed25519 secret matches the public ID, stores it in macOS Keychain,
203
+ Linux Secret Service, or Windows DPAPI, verifies readback, and only then atomically updates the
204
+ global profile. Replacement requires `--replace`. The public command contains no secret.
205
+
206
+ </details>
207
+
208
+ ## Security and protocol reference
209
+
210
+ <details>
211
+ <summary>Authentication, enforcement, budget uncertainty, providers and evidence</summary>
212
+
213
+ ### Request and authentication flow
18
214
 
19
215
  ```text
20
216
  Direct Agent Key ───────────────────────────────────────────────┐
@@ -55,7 +251,7 @@ these controls do not cancel an upstream request already in flight. Public lifec
55
251
  checks and the signed [revocation list](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md)
56
252
  are separate from signature verification.
57
253
 
58
- ## What the gateway enforces
254
+ ### What the gateway enforces
59
255
 
60
256
  - An allowlist of provider endpoints, plus the agent's provider/model scope.
61
257
  - Live policy rules: model/endpoint denials, time windows, request limits; optional
@@ -63,7 +259,11 @@ are separate from signature verification.
63
259
  - Token and cost admission limits through atomic reservations and settlement.
64
260
  - Platform/tenant kill switches and per-agent suspension/revocation.
65
261
  - Provider failover within supported request families and each attempt's authorization
66
- and budget checks; it is not arbitrary API translation.
262
+ and budget checks; it is not arbitrary API translation. Embeddings never fail over.
263
+ - The injected provider key is removed from what comes back: if an upstream echoes it in
264
+ an error body, a JSON answer or an event stream (even split across chunks), the agent
265
+ receives `[REDACTED_PROVIDER_KEY]` instead. This covers the exact key, not a key an
266
+ upstream has transformed.
67
267
 
68
268
  Passport scopes are snapshots in visas; scope edits can take up to the configured visa
69
269
  TTL to replace those snapshots. Other live controls have their own cache/invalidation
@@ -71,7 +271,7 @@ behavior. Kill-state reads default to fail-open; `KILL_SWITCH_FAIL_CLOSED=true`
71
271
  on kill/suspend read failure. Required sender-proof replay checks and DAK credential
72
272
  validation fail closed. Redis persistence and no-eviction configuration matter.
73
273
 
74
- ### Budgets under uncertainty
274
+ #### Budgets under uncertainty
75
275
 
76
276
  Admission reserves an **estimate**, not a provider invoice or a guaranteed upper bound.
77
277
  Concurrent attempts consume reserved headroom. Complete usage settles measured tokens
@@ -84,12 +284,21 @@ ending never runs leaves an open hold that does not expire. `may_have_dispatched
84
284
  means dispatch permission was claimed, not that billing is proven. Such a hold cannot
85
285
  be released as `not_spent` through recovery.
86
286
 
287
+ An agent can also have a **daily or monthly spend limit** (calendar UTC), checked in the
288
+ same reservation as its cumulative caps and refused with `402 blocked_budget_period` and a
289
+ `retry-after` to the next reset. A call counts toward the period it finishes in; spend
290
+ earlier in the period counts when the limit is set; an attempt that never settles keeps
291
+ counting until an operator resolves it. An **output ceiling** (`max_output_tokens` in the
292
+ agent's policy) refuses any request whose stated output limit is missing or larger — it is
293
+ never rewritten to fit.
294
+
87
295
  Lost or mismatched established budget generations cause `503 blocked_budget_state`,
88
296
  not a fresh allowance. Recovery is an explicit operator action over retained logs and
89
297
  adjustments; it cannot reconstruct missing evidence. See [Budget recovery](https://github.com/Vertias3u/PassControl/blob/main/docs/budget-recovery.md).
90
298
 
91
- Prices are an in-code estimate table. Unknown models on built-in endpoints use a
92
- provider fallback rate. **Custom endpoints are unpriced**, even when the model name
299
+ Prices are an in-code estimate table, one row per model, read from each provider's pricing
300
+ page. Under a dollar limit, a model with no row is refused `402 unpriced_model`; without one it
301
+ is estimated at the provider's highest listed rate. **Custom endpoints are unpriced**, even when the model name
93
302
  matches: logs mark cost unknown, receipts carry `unp`, and token accounting continues.
94
303
  The cost budget retains a proxy estimate; it does not become knowledge of actual dollars.
95
304
  Known/table-priced cost, conservative enforced spend, and open holds are different figures.
@@ -99,22 +308,28 @@ live open reservations marked **not yet charged**. The call table keeps observed
99
308
  charge in separate columns and can load older durable rows on demand. An unavailable database or
100
309
  Redis explanation is shown as unavailable, never as zero.
101
310
 
102
- ## Supported providers and endpoints
311
+ ### Supported providers and endpoints
103
312
 
104
313
  All paths below are relative to `/api/v1/<provider>`. SDK base URLs and aliases are in
105
314
  [the endpoint reference](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md).
106
315
 
107
316
  | Provider ID | Inference | Discovery |
108
317
  |---|---|---|
109
- | `openai` | Chat Completions and **POST Responses** | Models list/detail |
318
+ | `openai` | Chat Completions, **POST Responses** and **POST Embeddings** | Models list/detail |
110
319
  | `anthropic` | Messages | Models list/detail |
111
- | `groq`, `mistral`, `together` | OpenAI-compatible Chat Completions | Models list/detail |
320
+ | `mistral` | OpenAI-compatible Chat Completions and **POST Embeddings** | Models list/detail |
321
+ | `groq`, `together` | OpenAI-compatible Chat Completions | Models list/detail |
112
322
  | `deepseek` | OpenAI-compatible Chat Completions | Not proxied |
113
323
  | `gemini` | Google's **OpenAI-compatible** Chat Completions | Models list/detail |
324
+ | `xai` | **POST Responses** only (legacy Chat Completions refused) | Models list/detail |
325
+ | `azure` | Azure OpenAI v1: Chat Completions, **POST Responses** and **POST Embeddings**, at the resource address stored with the key | Models list |
114
326
 
115
- Gemini's native `generateContent` API is not supported. Responses support is OpenAI-only;
116
- response retrieval/deletion, embeddings, files, fine-tuning, batches, and token-counting
117
- endpoints are not proxied. Model availability still depends on your provider account.
327
+ Gemini's native `generateContent` API is not supported. Responses is served for OpenAI,
328
+ xAI and Azure; embeddings for OpenAI, Mistral and Azure, and an embeddings call never fails over, because
329
+ another model's vectors would not match the ones already stored. Response retrieval/deletion,
330
+ files, fine-tuning, batches, and token-counting endpoints are not proxied. OpenAI's hosted tools (web search, file search, code interpreter
331
+ and others billed outside tokens) and its search models are refused, because no token budget can
332
+ hold their fees. Model availability still depends on your provider account.
118
333
 
119
334
  Custom provider base URLs support compatible deployments such as Ollama, vLLM, or
120
335
  LiteLLM without adding provider IDs. They require operator opt-in:
@@ -124,7 +339,7 @@ refuses custom endpoints. Shape validation is **not full SSRF prevention**: it d
124
339
  resolve or pin DNS. Operators must control egress and trust the destination receiving
125
340
  the provider credential. Upstream redirects are refused, never followed.
126
341
 
127
- ## Receipts, statements, and identity evidence
342
+ ### Receipts, statements, and identity evidence
128
343
 
129
344
  A signed call receipt records the issuer's decision, authentication method, reported
130
345
  usage/cost, and (when read) a digest of client request bytes. It does not include the
@@ -160,116 +375,18 @@ that company. Only published bindings are attached to public evidence.
160
375
  The recording illustrates a stop control on successive calls; it does not show cancellation
161
376
  of an already-dispatched stream.
162
377
 
163
- ## Try Cloud
164
-
165
- [Request access to the free private beta](https://passcontrol.vertias.eu/beta), or try
166
- [the keyless browser demo](https://passcontrol.vertias.eu). The demo synthesizes model
167
- output; it does not exercise a billed provider.
168
-
169
- With Node installed:
170
-
171
- ```bash
172
- npm install -g passcontrol
173
- passcontrol login
174
- ```
175
-
176
- Login prints a device code and opens browser approval. Enter only the code from your
177
- own terminal: approval grants this machine a workspace control key. The CLI creates a
178
- Passport locally, registers its public key, saves configuration, and attempts a keyless
179
- governed call and receipt verification. That proof requires a gateway with demo and
180
- signing enabled; it is not a real-provider test. See [the tutorial](https://github.com/Vertias3u/PassControl/blob/main/TUTORIAL.md).
181
-
182
- Run **`passcontrol`** with no arguments in an interactive terminal to open the command
183
- browser: searchable grouped commands, recent actions, and configuration-aware options.
184
- Use `passcontrol --help` or explicit commands in scripts.
185
-
186
- ```bash
187
- passcontrol status
188
- passcontrol call "Say hello" # off/observe mode; real provider calls require a stored key
189
- passcontrol doctor --deep
190
- passcontrol key status
191
- passcontrol key migrate # move an existing file key to the OS store
192
- passcontrol logout
193
- ```
194
-
195
- The CLI supports macOS Keychain, Linux Secret Service (`secret-tool`), and Windows
196
- DPAPI-backed storage. File configuration may contain a storage marker instead of the
197
- Passport secret; explicit environment secrets take precedence. An unavailable OS store
198
- can use an existing file fallback with a warning. Custody shown by the gateway is
199
- **DECLARED evidence**, not proof of storage. The signer still reads key material into
200
- process memory; this is not a non-exportable hardware key.
201
-
202
- For a Passport issued in the dashboard for Sidecar or MCP, import it without putting the
203
- one-time secret in shell history:
204
-
205
- ```bash
206
- passcontrol passport import --global --gateway https://YOUR-PASSCONTROL-HOST \
207
- --id PUBLIC_PASSPORT_ID
208
- # paste the secret at the hidden prompt, or provide it on raw stdin
209
- ```
210
-
211
- The CLI proves the 32-byte Ed25519 secret matches the public ID, stores it in macOS Keychain,
212
- Linux Secret Service, or Windows DPAPI, verifies readback, and only then atomically updates the
213
- global profile. Replacement requires `--replace`. The public command contains no secret.
214
-
215
- ## Connect a real agent
216
-
217
- For example, the direct OpenAI configuration has this shape:
218
-
219
- ```bash
220
- export OPENAI_BASE_URL=https://YOUR-PASSCONTROL-HOST/api/v1/openai/v1
221
- export OPENAI_API_KEY=pc_agent_REVEAL_ONCE_VALUE
222
- export OPENAI_MODEL=gpt-4o-mini
223
- ```
224
-
225
- Use your dashboard's actual values; Anthropic uses its native base URL and key variables.
226
- Never paste a Passport private key into an API-key field.
227
-
228
- Add a provider credential in the dashboard and give the agent a concrete model within
229
- its scope and suitable budgets. Choose by what your client supports:
230
-
231
- | Client | Integration |
232
- |---|---|
233
- | Static base URL + API key | Dashboard **Connect an agent**: copy its provider-native URL and DAK |
234
- | Your JS/TS code | `PassControl` from `passcontrol/sdk`; [SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md) |
235
- | Static-key client needing Passport | `passcontrol sidecar`, then `passcontrol env <integration>` |
236
- | MCP client | `passcontrol mcp`; configure as below |
237
-
238
- Direct Agent Keys point the client at the PassControl gateway origin. Passport Sidecar clients
239
- point at loopback (default `http://127.0.0.1:8788`) and the sidecar forwards to the gateway.
240
- The sidecar adds per-request sender proof; the current SDK and MCP paths use bearer visas and are
241
- refused when sender proof is required.
242
-
243
- ```bash
244
- # Passport bridge: talks to Cloud or your self-hosted gateway
245
- passcontrol sidecar
246
- passcontrol env hermes
247
-
248
- # MCP: global Passport configuration, no secret in generated client config
249
- passcontrol configure claude-desktop --write
250
- # Also: cursor; claude-code prints its client-managed add command
251
- ```
252
-
253
- The sidecar listens on loopback by default and substitutes a visa for the client's dummy
254
- API key. Treat access to that local listener as access to the configured agent. It is
255
- not a sandbox against other processes running as you. Its provider CONNECT requests are
256
- refused; use base URLs rather than TLS interception.
378
+ </details>
257
379
 
258
- Presets: `openhands`, `aider`, `cline`, `continue`, `litellm`, `hermes`, `chatbox`, `jan`,
259
- `msty`, `cherry-studio`, `open-webui`, `librechat`, `generic`; MCP presets:
260
- `claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
261
- supported paths. [Hermes configuration](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
380
+ ## Self-host operations reference
262
381
 
263
- ## Self-host
382
+ <details>
383
+ <summary>Source setup, lifecycle, credential switching, production and portability</summary>
264
384
 
265
- The npm package contains the CLI and compiled SDK, not the application/database stack.
266
- `passcontrol setup` obtains the public source and starts a local development stack.
267
- It needs Git, Docker, the Supabase CLI, and Node/npm. The CLI package declares Node ≥18, but use **Node 22+ for the full stack**:
268
- locked Supabase dependencies need ≥20 and Wrangler needs ≥22.
385
+ The CLI package declares Node ≥18, but the full stack needs Node 22+: locked Supabase
386
+ dependencies need ≥20 and Wrangler needs ≥22. Use `passcontrol setup --no-open` to
387
+ suppress browser launch. From a source checkout, the equivalent development path is:
269
388
 
270
389
  ```bash
271
- passcontrol setup --no-open
272
- # Or from a source checkout:
273
390
  git clone https://github.com/Vertias3u/PassControl.git
274
391
  cd PassControl
275
392
  npm ci
@@ -298,7 +415,8 @@ global write could not override them safely. Clean up any still-active remote id
298
415
  original gateway.
299
416
 
300
417
  For production, configure [`.env.example`](https://github.com/Vertias3u/PassControl/blob/main/.env.example), use Supabase (plain Postgres
301
- is insufficient), apply the public migrations with `DATABASE_URL=… npm run migrate`,
418
+ is insufficient), set `DATABASE_URL` in your shell environment and apply the public migrations with
419
+ `npm run migrate`,
302
420
  and build/run the app. Supported paths are Next.js on Vercel, `npm run build` then
303
421
  `npm start` on a Node host behind a trusted reverse proxy, and the
304
422
  [Cloudflare/OpenNext build](https://github.com/Vertias3u/PassControl/blob/main/docs/deployment/cloudflare.md). Configure Auth/SMTP,
@@ -321,14 +439,7 @@ as sensitive configuration and inspect the result for partial/refused items.
321
439
  [Release updates](https://passcontrol.vertias.eu/updates) and the
322
440
  [learning center](https://passcontrol.vertias.eu/learn) are hosted-site resources.
323
441
 
324
- ## Limits and security status
442
+ </details>
325
443
 
326
- PassControl governs requests routed through it. It cannot prevent an agent from using
327
- another credential or network path, secure a compromised signer, guarantee a provider's
328
- usage report, or make an issuer's assertions independently true. Short visas, stop controls,
329
- pricing tables, and best-effort logs each have the limits described above.
330
-
331
- Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/Vertias3u/PassControl/security/advisories/new).
332
- See [SECURITY.md](https://github.com/Vertias3u/PassControl/blob/main/SECURITY.md), [API documentation](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md), and
333
- [contributing](https://github.com/Vertias3u/PassControl/blob/main/CONTRIBUTING.md). No independent audit or production assurance is implied
334
- by the test suite. Read [LICENSE](./LICENSE) for the actual usage terms.
444
+ For the full reference, see [API documentation](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md).
445
+ Contributions: [CONTRIBUTING.md](https://github.com/Vertias3u/PassControl/blob/main/CONTRIBUTING.md).