foldrun 19.2.1 → 19.2.3

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/docs/a2a.md CHANGED
@@ -121,7 +121,7 @@ each is ticked. From the terminal:
121
121
  `foldrun a2a publish <flow> --to <ws> --accept-risk <agent,…>` (every agent
122
122
  accepted, as the list replaces the flow's; `--clear-accept-risk` takes it
123
123
  out). `foldrun a2a ls --to <ws>` lists them, and
124
- [`security/published-flow-secret-code`](checks#securitypublished-flow-secret-code)
124
+ [`security/published-flow-secret-code`](checks#security-published-flow-secret-code)
125
125
  is `foldrun check`'s warning.
126
126
 
127
127
  ### An editor cannot widen a published flow
@@ -402,12 +402,12 @@ Ended tasks are kept 90 days.
402
402
  and an editor cannot widen any agent of a published flow
403
403
  ([above](#an-editor-cannot-widen-a-published-flow)).
404
404
  - **`foldrun check` warns on three shapes** of published flow (warnings, not
405
- errors): [`security/published-flow-trifecta`](checks#securitypublished-flow-trifecta)
405
+ errors): [`security/published-flow-trifecta`](checks#security-published-flow-trifecta)
406
406
  — an agent of the flow that holds something private, which a caller could
407
407
  ask for in the answer or steer into sending;
408
- [`security/published-flow-secret-code`](checks#securitypublished-flow-secret-code)
408
+ [`security/published-flow-secret-code`](checks#security-published-flow-secret-code)
409
409
  — one that holds a secret and can run code (info once accepted); and
410
- [`security/published-flow-ungated`](checks#securitypublished-flow-ungated)
410
+ [`security/published-flow-ungated`](checks#security-published-flow-ungated)
411
411
  — a step that acts outside the workspace with no approval or `ask:` before
412
412
  it, which any key holder starts. Put a gate (`2!.`) on it, or take a leg
413
413
  away.
package/docs/agents.md CHANGED
@@ -264,7 +264,7 @@ What it may reach and send:
264
264
  - **Untrusted.** What a remote answers reaches the model fenced as data from
265
265
  another organisation's system, with invisible characters removed. An agent
266
266
  with `remotes:` counts as reading untrusted content in the
267
- [lethal-trifecta check](checks#securitylethal-trifecta).
267
+ [lethal-trifecta check](checks#security-lethal-trifecta).
268
268
  - **Limits.** `limits: {a2a: 10}` caps the messages a step sends (`a2a_send`
269
269
  and `a2a_reply`); `a2a.status`, `a2a.send`, `a2a.reply` and `a2a.cancel` cap
270
270
  each tool alone, so polling is capped apart from sending. A step sends at
@@ -382,7 +382,7 @@ What holds:
382
382
  serve a writer with secrets and no web: a page that tells the reader to
383
383
  send something finds nothing to send, and the writer never read the page.
384
384
  `foldrun check` names what it holds that the parent does not
385
- ([`security/subagent-own-sandbox`](checks#securitysubagent-own-sandbox)).
385
+ ([`security/subagent-own-sandbox`](checks#security-subagent-own-sandbox)).
386
386
  - **Only the reply comes back.** The reply is still text the parent reads —
387
387
  it can carry an instruction — but it reaches a model whose sandbox never
388
388
  held the page.
package/docs/api-usage.md CHANGED
@@ -29,7 +29,7 @@ Foldrun-Version: 2026-10-01
29
29
 
30
30
  Every response says which version answered it, in `Foldrun-Version`.
31
31
 
32
- - **No header**: for an API key, your account's pin (**Settings → API**, or
32
+ - **No header**: for an API key, your account's pin (**Settings → API keys → API**, or
33
33
  `PATCH /api/account/api {"version": "2026-10-01"}`), and with no pin, the
34
34
  current version. The dashboard always uses the current version: it ships
35
35
  with the platform, so a pin never applies to it.
@@ -76,7 +76,7 @@ shows the platform, and warns when its commands would be refused.
76
76
  can only be removed once its deprecation has passed its sunset date.
77
77
  - **You are told if it affects you.** Every request is counted by the
78
78
  version that answered it, and a call to a deprecated route by the key or
79
- person that made it. **Settings → API** and `foldrun api version` show the
79
+ person that made it. **Settings → API keys → API** and `foldrun api version` show the
80
80
  last 30 days. An account that called a deprecated route in the last 30
81
81
  days is emailed when it is first seen doing so, and again 90, 30 and 7
82
82
  days before the sunset — one email per step, naming the keys that still
@@ -120,7 +120,7 @@ Over the limit the answer is `429`, with `Retry-After` in seconds and
120
120
  { "error": "rate limit: this API key may make 120 writes a minute — retry in 41s", "retry_after": 41 }
121
121
  ```
122
122
 
123
- Your account's limits are on **Settings → API** and at `GET /api/account/api`.
123
+ Your account's limits are on **Settings → API keys → API** and at `GET /api/account/api`.
124
124
  The counters are shared by every server in the deployment. A self-hosted
125
125
  install can switch them off with `FOLDRUN_API_RATE_LIMIT=off` (for example
126
126
  behind its own gateway).
@@ -25,9 +25,9 @@ mistake the editor names rather than a cap it quietly keeps.
25
25
  When an agent's cap and the flow's both apply to one step, the tighter one
26
26
  wins, and the step's error says which line set it: `budget: in the flow
27
27
  file` or `budget: on the writer agent`.
28
- | **runs at once** | `concurrency: 3` in the account's `AGENTS.md`, or Settings → Governance | the fourth run waits its turn in the queue — never refused, only later. Empty means the install's share (`FOLDRUN_ACCOUNT_CONCURRENCY`) or plan number (`FOLDRUN_PLAN_CONCURRENCY`, which applies only where billing is on), or no cap. Your own number can lower that, never raise it; a higher number comes with a plan |
28
+ | **runs at once** | `concurrency: 3` in the account's `AGENTS.md`, or Settings → Policies → Governance | the fourth run waits its turn in the queue — never refused, only later. Empty means the install's share (`FOLDRUN_ACCOUNT_CONCURRENCY`) or plan number (`FOLDRUN_PLAN_CONCURRENCY`, which applies only where billing is on), or no cap. Your own number can lower that, never raise it; a higher number comes with a plan |
29
29
  | **the queue lane** | the plan's lane (`high` \| `normal` \| `low`); `priority: low` in the account's `AGENTS.md` lowers it, and `high` there counts only with a plan that gives it | when slots are short, accounts take turns, weighted by lane — high 3, normal 2, low 1: every account's first run goes before anyone's second, a fast lane takes three turns to a slow lane's one and never all of them, an account with runs going waits behind one with none, and a run that has waited ten minutes moves up a turn. A flow's own `priority:` orders runs within that. The cap above still holds |
30
- | **compute at once** | the plan's cores, GiB and disk (below); `compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }` in the account's `AGENTS.md`, or Settings → Governance, lowers it — and a workspace's and a flow's `compute:` narrow it further ([four levels](#compute-at-four-levels)) | what all the account's running steps may hold together — each step's cores, memory and disk, its `size:` class's or its own `resources:` ([agents](agents#resources-your-own-numbers)). A step that would pass it waits to start, like a full node — `room: waiting to start — 6 of this account's 8 GiB is held by its running steps…` — and starts in turn when one of the account's steps ends ([waiting for room](#waiting-for-room)). A step that **alone** is bigger than the pool, or than the plan's most for one step, fails at once with that message: no step finishing would make room. Without a plan, the install's `FOLDRUN_ACCOUNT_VCPU` / `FOLDRUN_ACCOUNT_MEMORY_GIB` / `FOLDRUN_ACCOUNT_DISK_GIB`, or no cap. Your own number can lower it, never raise it. `foldrun usage compute` shows the pool and what is held now. Enforced on the hosted platform and any k8s install; a self-hosted Docker install caps each step at its class but not the pool |
30
+ | **compute at once** | the plan's cores, GiB and disk (below); `compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }` in the account's `AGENTS.md`, or Settings → Policies → Governance, lowers it — and a workspace's and a flow's `compute:` narrow it further ([four levels](#compute-at-four-levels)) | what all the account's running steps may hold together — each step's cores, memory and disk, its `size:` class's or its own `resources:` ([agents](agents#resources--your-own-numbers)). A step that would pass it waits to start, like a full node — `room: waiting to start — 6 of this account's 8 GiB is held by its running steps…` — and starts in turn when one of the account's steps ends ([waiting for room](#waiting-for-room)). A step that **alone** is bigger than the pool, or than the plan's most for one step, fails at once with that message: no step finishing would make room. Without a plan, the install's `FOLDRUN_ACCOUNT_VCPU` / `FOLDRUN_ACCOUNT_MEMORY_GIB` / `FOLDRUN_ACCOUNT_DISK_GIB`, or no cap. Your own number can lower it, never raise it. `foldrun usage compute` shows the pool and what is held now. Enforced on the hosted platform and any k8s install; a self-hosted Docker install caps each step at its class but not the pool |
31
31
  | **room to start** | the install's `FOLDRUN_RUN_MEMORY_GIB`, `FOLDRUN_RUN_DISK_GIB` and `FOLDRUN_ACCOUNT_PODS` | a step whose sandbox would not fit, or whose account already has its most sandboxes running, waits to start — `room: waiting to start — …` on its trail — instead of failing. The wait is not billed and has no time limit; the run page's start-up chip shows it as `room` ([waiting for room](#waiting-for-room)) |
32
32
 
33
33
  A cap is a literal, never an expression, so it is readable off the file. The
@@ -65,8 +65,8 @@ level only narrows the one above it; a step must fit all of them.
65
65
 
66
66
  | level | where | what it caps |
67
67
  |---|---|---|
68
- | **account** | the plan (or the install's `FOLDRUN_ACCOUNT_*`); `compute:` in the account's `AGENTS.md`, Settings → Governance or `foldrun account set compute` lowers it | everything the account's running steps hold together |
69
- | **workspace** | `compute:` in the workspace's `AGENTS.md`, its Settings → Governance, or `foldrun workspace set compute … --to <ws>` | what that workspace's running steps hold together |
68
+ | **account** | the plan (or the install's `FOLDRUN_ACCOUNT_*`); `compute:` in the account's `AGENTS.md`, Settings → Policies → Governance or `foldrun account set compute` lowers it | everything the account's running steps hold together |
69
+ | **workspace** | `compute:` in the workspace's `AGENTS.md`, its Settings → Policies → Governance, or `foldrun workspace set compute … --to <ws>` | what that workspace's running steps hold together |
70
70
  | **run** | `compute:` in the flow, the flow's card, or `foldrun flow compute <flow> …` | what one run of the flow holds at once across its parallel steps — each run has its own |
71
71
  | **step** | the agent's `size:` or `resources: { cpu, memory, disk }`; the plan's (or install's `FOLDRUN_STEP_MAX_*`) most for one step — on foldrun's hosted platform an account without a plan, or whose plan sets none, gets the entry plan's | one step's sandbox |
72
72
 
@@ -107,7 +107,7 @@ fails, at once, because nothing finishing would make room.
107
107
  running waits beside it. A wait is not a try: it spends none of the
108
108
  step's `retry:`, and a stop ends it like any other.
109
109
  - **Seen.** The run page says *Waiting for room to start*, why, and since
110
- when; Settings → Governance and `foldrun usage compute` list every
110
+ when; Settings → Policies → Governance and `foldrun usage compute` list every
111
111
  waiting step, oldest first (`waiting` in `GET /api/usage/compute`).
112
112
  - **Told.** After an hour (`FOLDRUN_ROOM_ALERT_MIN`) the workspace's
113
113
  `notify:` hears of it once, as event `room`, with what to change: ask for
@@ -161,7 +161,7 @@ that is running.
161
161
  `wait:`, or back for room — so the count can pass the limit for a while;
162
162
  new runs are refused until it falls below. Two starts in the same instant
163
163
  may both take the last place.
164
- - **Seen.** Settings → Governance → Compute and `foldrun usage compute`
164
+ - **Seen.** Settings → Policies → Governance and `foldrun usage compute`
165
165
  show *N of M runs waiting for their turn* (`runsWaiting` in
166
166
  `GET /api/usage/compute`).
167
167
 
@@ -264,7 +264,7 @@ per-seat fee would tax the approver the safety story depends on.
264
264
  is billed to your own provider account — so a plan then buys sandbox time
265
265
  and the platform, which is most of what a BYOK customer's credits go on.
266
266
  A step counts as BYOK when it ran on a key of the account's own (Settings →
267
- Model, or a `provider:` block); the run page says which credential each step
267
+ Models, or a `provider:` block); the run page says which credential each step
268
268
  used. On a hosted platform every customer account brings one
269
269
  ([providers](providers.md#your-accounts-own-model-key)).
270
270
 
@@ -316,7 +316,7 @@ cost from what the last one consumed.
316
316
  An account on [foldrun's models](providers.md#foldruns-models) pays for each
317
317
  model call at **foldrun's price list** — per million input, output,
318
318
  cache-read and cache-write tokens, per model — times the margin in force.
319
- Settings → Model provider shows the list as you pay it, and so does
319
+ Settings → Models shows the list as you pay it, and so does
320
320
  `foldrun account model prices`. A model not on it is refused.
321
321
 
322
322
  - **Metered per call**, by the platform's model gateway, from the usage the
@@ -463,7 +463,7 @@ they are kept and sent with the next save or payment.
463
463
  **Manage in Stripe.** The Payment, Plan, Invoices and Details tabs carry a
464
464
  button into Stripe's Billing Portal — the card, every invoice as a PDF, the
465
465
  plan — for the owner. Its look and what it allows (cancelling, switching
466
- plan) are set once at Stripe, under Settings → Billing → Customer portal.
466
+ plan) are set once in Stripe's own Dashboard, under Settings → Billing → Customer portal.
467
467
 
468
468
  **When a plan payment fails.** Stripe retries the card on its own
469
469
  schedule. On the first failure of an invoice the owner is emailed once —
package/docs/checks.md CHANGED
@@ -81,7 +81,7 @@ listed with it. `deploy_block:` in `AGENTS.md` turns them into refusals:
81
81
  | `security` | any security finding: `secret/*`, `content/*`, `security/*`, `supply-chain/*`, and `flow/outward-ungated` (a step that acts outside with no check or approval) |
82
82
 
83
83
  Set it in the account's `AGENTS.md` for every workspace, or in one
84
- workspace's `AGENTS.md`, which wins. Settings → Governance → **Refuse a
84
+ workspace's `AGENTS.md`, which wins. Settings → Policies → Governance → **Refuse a
85
85
  deploy on**, or `foldrun account set deploy_block secrets`. A refused
86
86
  deploy names each finding and its rule; a `foldrun-ignore` with a reason
87
87
  (below) still accepts one.
@@ -90,9 +90,9 @@ deploy names each finding and its rule; a `foldrun-ignore` with a reason
90
90
 
91
91
  `foldrun check` stays offline. Two checks need the network, so they run on
92
92
  the platform against the deployed copy: known vulnerabilities for exact
93
- runtime pins ([`supply-chain/known-vulnerability`](#supply-chainknown-vulnerability))
93
+ runtime pins ([`supply-chain/known-vulnerability`](#supply-chain-known-vulnerability))
94
94
  and the tool text of MCP servers reached by URL
95
- ([`content/mcp-tool-text`](#contentmcp-tool-text)).
95
+ ([`content/mcp-tool-text`](#content-mcp-tool-text)).
96
96
 
97
97
  - **When you ask:** Checks → **Online checks**, `foldrun check --to <ws>
98
98
  --online`, or `GET /api/workspaces/<ws>/check?online=1` — editor and
@@ -299,7 +299,7 @@ is the other answer, though this rule looks at the agent, not the flow.
299
299
  sub-agent never gets more than its parent, so they are dropped inside the
300
300
  delegation. Grant them to the parent, or remove them from the sub-agent.
301
301
  A sub-agent with `sandbox: own` is not this rule's: its tools are its own
302
- ([below](#securitysubagent-own-sandbox)).
302
+ ([below](#security-subagent-own-sandbox)).
303
303
 
304
304
  ### security/subagent-own-sandbox
305
305
 
@@ -465,7 +465,7 @@ at `high`, Kimi has `low`, `high` and `max`, DeepSeek runs `medium` and
465
465
  `xhigh` as `high`. The step is not refused: it runs at the nearest level the
466
466
  model has, and its log says so, so a file stays valid when the account
467
467
  changes provider. Write a level the model has, or choose a provider whose
468
- model has the one you want (Settings → Model provider). Checked on the
468
+ model has the one you want (Settings → Models). Checked on the
469
469
  platform (the Checks page, a save, a deploy) when the account runs on
470
470
  foldrun's models; `foldrun check` offline does not know the account's
471
471
  choice, and an agent or workspace with its own `provider:` is not checked.
package/docs/cli.md CHANGED
@@ -119,7 +119,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
119
119
  | `foldrun answer <run-id> "…"` | answer the question an agent is asking mid-step (`tools: [ask]`). `--option <n>` picks one of the choices it offered; `--question <id>` one of several. The agent is waiting in its sandbox and carries on at once. `foldrun approvals` lists what is being asked |
120
120
  | `foldrun message <run-id> "…"` | say something to a running agent. It reaches the model after its next tool call, as context — it changes none of the step's tools. `--step <n>` picks one when a parallel group has several running. Platform only |
121
121
  | `foldrun secrets set NAME` | store a secret — also `ls`, `rm`, and `status` (OAuth grant health). `rm` of an oauth2 secret also revokes its grant at the provider when it has a revocation URL, and says if that failed. `--site <domain>` (repeatable, or `a,b`) binds it as it is stored. `--account --workspaces a,b` stores an account secret limited to those workspaces in the same write, so it is never open in between; `--account --none` to no workspace yet (`secrets workspaces` changes it later). The account's `RESEND_API_KEY` and `EMAIL_FROM` (the sender of everyone's reset mail) are refused from the CLI: the owner sets them signed in, in Settings → Secrets |
122
- | `foldrun secrets ls` | the secrets in scope — where each is set, shadowed or not, its sites and the workspaces an account secret is limited to — and, on the platform, whether the far end still takes it: accepted by its host on a date, refused (with the status, how many times running and when it last worked), the host's own failure ("its end, not the key"), or not used yet, as Settings → Connections shows it. `--json` prints the document (`GET /api/secrets`) |
122
+ | `foldrun secrets ls` | the secrets in scope — where each is set, shadowed or not, its sites and the workspaces an account secret is limited to — and, on the platform, whether the far end still takes it: accepted by its host on a date, refused (with the status, how many times running and when it last worked), the host's own failure ("its end, not the key"), or not used yet, as Settings → Secrets → Connections shows it. `--json` prints the document (`GET /api/secrets`) |
123
123
  | `foldrun secrets rm NAME` | delete one (asks; `--yes` on a pipe). An oauth2 secret's grant is revoked at the provider. When an account secret leaves the OAuth client saved under its name unused, the CLI says so with the command that removes it (`secrets clients rm <name>`) — the dashboard deletes it with the secret; `--with-client` does that here too, after asking. A client another connection still uses is never touched |
124
124
  | `foldrun secrets sites NAME [site…]` | bind a secret to the sites it is for: the egress proxy fills it in requests to those sites alone, and it never enters a sandbox ([bound to sites](secrets#bound-to-sites)). No sites prints what it is bound to; `--clear` unbinds. On the platform, or this machine's vault with `--local` |
125
125
  | `foldrun secrets workspaces NAME [workspace…]` | limit an account secret to those workspaces: every other one finds it not set (`PATCH /api/secrets { name, workspaces }`). `--all` opens it to every workspace again, `--none` to no workspace; no names prints which may use it. An admin over every workspace; it applies to runs that start after it |
@@ -158,13 +158,13 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
158
158
  | `foldrun team remove <email\|id>` | remove a member (`DELETE /api/team/members/<id>`). Asks first; with no terminal it needs `--yes`. Their keys and the invites they made stop with them. Transferring the account stays in Settings → Team (signed in, with your password) |
159
159
  | `foldrun me` | the person this machine is signed in as (`GET /api/me`'s `person`): name, address, account, role, timezone. `--json`. A key made by hand is nobody: it says so and exits 1 |
160
160
  | `foldrun me name <first> [last]` | set your name (`POST /api/auth/name`); `--clear` for none, so you are shown by your address |
161
- | `foldrun me timezone <zone\|auto>` | the zone you read times in (`POST /api/auth/timezone`), e.g. `Australia/Sydney`; `auto` goes back to the browser's. Password, email, two-step sign-in and sessions stay in Settings → Profile |
161
+ | `foldrun me timezone <zone\|auto>` | the zone you read times in (`POST /api/auth/timezone`), e.g. `Australia/Sydney`; `auto` goes back to the browser's. Password, email, two-step sign-in and sessions stay in Profile |
162
162
  | `foldrun team invites` | the account's pending invites (`GET /api/team/invites`): the address, or "anyone with the link", role, workspaces, who made it, when it expires, and its id. `--all` adds accepted, revoked and expired ones; `--json`. Never the link: an invite works once and its link is shown only to the person who made it. An admin's (`team:manage`), a key included; a scoped key sees the invites inside its scope |
163
163
  | `foldrun team invites revoke <id>` | take an invite back (`DELETE /api/team/invites/<id>`): its link stops working at once. One already revoked or expired says so and changes nothing; one already accepted is refused (remove the member in Settings → Team instead). An admin invite is the owner's to revoke |
164
164
  | `foldrun onboarding` | the account's getting-started steps — the model key (where the account brings its own), workspace, agent, a run, a run that completes, a secret, a schedule or webhook, a teammate, billing where the plan asks for it, the CLI — each worked out from what is really there, with the next one first and where to do it (`--json`). `--to <workspace>` adds that workspace's checklist: a flow that ran to the end, a schedule or webhook, an owner, an eval, `notify:` — each with where it is done (`GET /api/me/onboarding?workspace=`). Hiding the card, a step or a checklist item is per person, from the dashboard |
165
165
  | `foldrun preferences` | your own settings on the platform — today the theme (`system`, `light`, `dark`), kept with you on every browser; `preferences set theme dark` changes it (`/api/me/preferences`; a key acts for whoever minted it) |
166
166
  | `foldrun api spec` | the platform's OpenAPI 3.1 document, from `GET /api/openapi.json` (no key needed) — to stdout, or `--out <file>`. Every other command sends `Foldrun-Version` (the API version this CLI was built for), an `Idempotency-Key` on each write (reused on its own retry), and waits out one `429` for `Retry-After` before saying so. See [Using the API](api-usage) |
167
- | `foldrun api version` | Settings → API: the API version this account's requests get when they send no `Foldrun-Version`, whether it is pinned, every version still served, the rate limits, and the last 30 days: requests by version, and any deprecated route the account still calls — by which key or person, and when it stops answering. `api version pin <YYYY-MM-DD>` pins it, `unpin` goes back to current (`PATCH /api/account/api`; an admin's) |
167
+ | `foldrun api version` | Settings → API keys → API: the API version this account's requests get when they send no `Foldrun-Version`, whether it is pinned, every version still served, the rate limits, and the last 30 days: requests by version, and any deprecated route the account still calls — by which key or person, and when it stops answering. `api version pin <YYYY-MM-DD>` pins it, `unpin` goes back to current (`PATCH /api/account/api`; an admin's) |
168
168
  | `foldrun changelog` | What's new: first the API — its current version, the breaking changes each dated version brought, and the routes deprecated with their sunset dates — then the platform's release notes, newest first — features, fixes, docs — and which release this install runs (`GET /api/changelog`; `--limit <n>` up to 50, `--json`) |
169
169
  | `foldrun version` | this CLI's version, its `@foldrun/core`'s, and — when a platform is known (`--url`, `--profile`, `FOLDRUN_URL` or where you signed in) — that platform's: version, release time, API version, each component's commit and the browsers its runner image has (with versions where known: `chrome 154.0.8037.58`), from `GET /api/version` (no key needed). Warns when the platform was released with a newer CLI than this one. An unreachable platform is a dim line, not a failure. `--json` prints `{ cli, core, platform }`. `foldrun --version` (or `-v`) prints only the CLI's version, offline. See [Versions and releases](versions) |
170
170
  | `foldrun doctor` | check the road to the platform, one line each: Node (22 or newer), the CLI and core versions, which of `FOLDRUN_URL`, `FOLDRUN_TOKEN`, `FOLDRUN_TIMEOUT`, `HTTPS_PROXY` are set (never their values), which model credential a local run would use (by its variable, never its value), the account it would act as, DNS for the platform's host, and a timed `GET /api/healthz`. The first thing to run when a command cannot reach the platform |
@@ -247,7 +247,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
247
247
  | `--dismissed`, `--unread` | `inbox`: what you set aside; only what you have not read |
248
248
  | `--models <m[:effort],…>` | `eval compare`: the settings to compare — two to four tiers or model ids, each with an optional `:effort` |
249
249
  | `--if-version <n>` | `account model use`: change the choice only while it is still that `choiceVersion` (`account model --json` shows it; 0: never chosen) — refused (409) when someone chose since, as Settings does |
250
- | `--if-workspaces <a,b\|all\|none>` | `secrets workspaces`: change the list only while it is still the one you read — refused (409) when another admin changed it since, as Settings → Connections does |
250
+ | `--if-workspaces <a,b\|all\|none>` | `secrets workspaces`: change the list only while it is still the one you read — refused (409) when another admin changed it since, as Settings → Secrets → Connections does |
251
251
  | `--max-usd <n>` | `eval compare`: stop starting runs once the runs and judges have spent this (default 5) |
252
252
  | `--payload <file\|-\|json>` | `flow filter`: the delivery to test — a file, `-` for stdin, or JSON inline |
253
253
  | `--kind <k>` | `secrets set`: `file`, `ssh`, `api`, `service-account` or `m2m` — each with its own flags, in the `secrets set NAME --kind` row above |
package/docs/faq.md CHANGED
@@ -13,7 +13,7 @@ with a team.
13
13
  **Which models does it use?** Whatever you point it at. `model:` takes a
14
14
  tier — `fast`, `default`, `max` — and the platform resolves the tier to a
15
15
  model. Bring your own key for any provider that speaks the Anthropic or the
16
- Chat Completions API — once for the whole account in Settings → Model
16
+ Chat Completions API — once for the whole account in Settings → Models
17
17
  (`foldrun account model set`), or per workspace or agent with a `provider:`
18
18
  block — and the platform bills you nothing for those tokens. On a hosted
19
19
  platform every account brings its own API key — Claude login tokens are not
package/docs/four-jobs.md CHANGED
@@ -79,10 +79,10 @@ a workspace that sets only `effort` keeps the account's `model`.
79
79
 
80
80
  | Job | In the dashboard | In the CLI |
81
81
  |---|---|---|
82
- | Governance | Settings → Governance: owner, budget, deploy rules, pause, team, API | `foldrun jobs`, `foldrun account set governance.<field>` |
83
- | Guardrail | Settings → Guardrail: network enforcement; each agent's page | `foldrun check --security`, `foldrun agent network` |
84
- | Observability | Settings → Observability: notify, alerts, telemetry; Observe, Issues | `foldrun issues`, `foldrun account telemetry` |
85
- | Evaluation | Settings → Evaluation: the judge; the Evals page | `foldrun eval --to <workspace>` |
82
+ | Governance | Settings → Policies → Governance: owner, budget, deploy rules, pause, team, API | `foldrun jobs`, `foldrun account set governance.<field>` |
83
+ | Guardrail | Settings → Policies → Guardrail: network enforcement; each agent's page | `foldrun check --security`, `foldrun agent network` |
84
+ | Observability | Settings → Policies → Observability: notify, alerts, telemetry; Observe, Issues | `foldrun issues`, `foldrun account telemetry` |
85
+ | Evaluation | Settings → Policies → Evaluation: the judge; the Evals page | `foldrun eval --to <workspace>` |
86
86
 
87
87
  `foldrun jobs` prints all four; with `--to <workspace>`, each field's value
88
88
  there, the account's, and how the two combine. They do not all simply
@@ -136,7 +136,7 @@ teammate, set up billing (where the plan asks for it) and install the CLI —
136
136
  account as it is (a run on record, a secret in the vault, a key minted for
137
137
  the CLI), so it ticks itself whichever way you did the thing; there is
138
138
  nothing to mark. While an account has no model key every dashboard page also
139
- carries a banner saying so, with a link to Settings → Model provider
139
+ carries a banner saying so, with a link to Settings → Models
140
140
  (`foldrun account model set anthropic --key …`, or on foldrun's own platform
141
141
  `foldrun account model use foldrun --provider anthropic` to run on foldrun's
142
142
  models, billed in credits). A step's **…** menu hides that step for you; the
package/docs/mcp.md CHANGED
@@ -74,7 +74,7 @@ claude mcp add --transport http foldrun https://<your platform>/api/mcp \
74
74
  --header "Authorization: Bearer mda_..."
75
75
  ```
76
76
 
77
- Settings → API keys → **Connecting an AI app (MCP)** shows this install's
77
+ Settings → API keys → **Connect an AI app (MCP)** shows this install's
78
78
  address and the same lines.
79
79
 
80
80
  ## Connected apps
package/docs/network.md CHANGED
@@ -233,7 +233,7 @@ The list is refused when any one of three says so:
233
233
 
234
234
  Each only switches it on. A workspace cannot turn off what its account
235
235
  turned on, and nothing in an account turns off the install's. Settings →
236
- Guardrail, on the account's and a workspace's Settings, has the switch, and so does
236
+ Policies → Guardrail, on the account's and a workspace's Settings, has the switch, and so does
237
237
  `foldrun account set network_enforce on` / `foldrun workspace set
238
238
  network_enforce on --to <workspace>`.
239
239
 
@@ -149,7 +149,7 @@ Three watch for behaviour that is out of character rather than broken:
149
149
  usual".
150
150
  - `runs_per_hour` — one flow started that many times in the last hour: a
151
151
  loop, a webhook sender retrying, a schedule written wrong. At most once a
152
- day per flow. `throttle:` caps it for good; Settings → Governance → Pause stops it now.
152
+ day per flow. `throttle:` caps it for good; Settings → Policies → Pause runs stops it now.
153
153
  - `new_host` — after each run, the sites every agent reached (from the
154
154
  egress lines on its trail) are compared with what it reached before, and a
155
155
  new one is told: "blog-desk: agent researcher reached a site it never
package/docs/oauth.md CHANGED
@@ -23,7 +23,7 @@ authorization server (Keycloak) and against recorded provider answers.
23
23
 
24
24
  | What | Spec | Status | How, or why not |
25
25
  |---|---|---|---|
26
- | Authorization code with PKCE (S256) | RFC 6749 §4.1, RFC 7636 | Supported | Settings → Connections or `foldrun connect`. PKCE is on for every connection. |
26
+ | Authorization code with PKCE (S256) | RFC 6749 §4.1, RFC 7636 | Supported | Settings → Secrets → Connections or `foldrun connect`. PKCE is on for every connection. |
27
27
  | Refresh, and refresh-token rotation | RFC 6749 §6, RFC 9700 §2.2.2 | Supported | Refreshed before every use; a rotated refresh token replaces the stored one. |
28
28
  | Client credentials (machine to machine) | RFC 6749 §4.4 | Supported | The "OAuth — client credentials" connection, or `foldrun secrets set NAME --kind m2m`. |
29
29
  | Client secret in the form body | RFC 6749 §2.3.1 | Supported | The default (`token_auth: client_secret_post`). |
package/docs/providers.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Your account's own model key
4
4
 
5
- The simplest way to bring a key: **Settings → Model provider**, or
5
+ The simplest way to bring a key: **Settings → Models**, or
6
6
  `foldrun account model set <provider> --key <api key>`, or
7
7
  `PUT /api/account/model`. Pick a name from the table below (or `custom`
8
8
  with a base URL and a format), paste an **API key**, and every step in
@@ -37,7 +37,7 @@ time for the whole account. No provider account is needed; the tokens are
37
37
  billed in credits at **foldrun's price list**
38
38
  ([budgets and billing](budgets-and-billing.md#foldruns-models)).
39
39
 
40
- - **Choose it:** Settings → Model provider → *foldrun's models*, pick the
40
+ - **Choose it:** Settings → Models → *foldrun's models*, pick the
41
41
  provider, *Use*. Or `foldrun account model use foldrun --provider openai`,
42
42
  or `PUT /api/account/model` with `{ "source": "foldrun", "supply": "openai" }`.
43
43
  An admin chooses, as for the key. `foldrun account model use own` (or the
@@ -268,7 +268,7 @@ what would be checked; `POST` forces one, for the minute after rotating a
268
268
  key. From the terminal, `foldrun account providers` prints the same table
269
269
  (✓, ✗ with the verdict, or · for never checked) and `--check` forces one;
270
270
  a dead key is a non-zero exit, so a deploy script can refuse to continue.
271
- In the dashboard, Settings → Model provider shows the same check per
271
+ In the dashboard, Settings → Models shows the same check per
272
272
  provider, with **Check now** (editor and above, since it spends a request).
273
273
 
274
274
  ## When a provider says no, the run says why
package/docs/runs.md CHANGED
@@ -213,7 +213,7 @@ telemetry:
213
213
  authorization: ${OTEL_TOKEN} # a vault secret, by name
214
214
  ```
215
215
 
216
- In the account's `AGENTS.md` (Settings → Observability → *Send runs to your
216
+ In the account's `AGENTS.md` (Settings → Policies → Observability → *Send runs to your
217
217
  tracing*, or `foldrun account telemetry set <url> --header
218
218
  authorization='${OTEL_TOKEN}'`), or a workspace's, which replaces the
219
219
  account's whole. Every run that finishes is sent as one trace. Resource
@@ -560,7 +560,7 @@ Sooner is yours to decide:
560
560
  - everything that started before a date: `foldrun runs rm --until 30d`
561
561
  (or `--until 2026-08-01`, `--to <workspace>`, `--dry-run`), which is
562
562
  `POST …/runs/bulk { action: "delete", until }` — finished runs only;
563
- - the whole account: close it (Settings → Account); the platform team then
563
+ - the whole account: close it (Settings → General → Close this account); the platform team then
564
564
  deletes its data.
565
565
 
566
566
  Deleting needs an admin (`workspace:manage`). What the charge was stays on
package/docs/secrets.md CHANGED
@@ -116,7 +116,7 @@ with the platform's keys, the rename or delete is refused and names it — set
116
116
  it again or delete it, then try again. Only an admin with access to every
117
117
  workspace sets the limit, and the account's `RESEND_API_KEY` and `EMAIL_FROM`
118
118
  stay the owner's, signed in (no key, not even `foldrun login`). The account's own uses of a secret — its model key in
119
- Settings → Model, and the mail the platform sends for the account (password
119
+ Settings → Models, and the mail the platform sends for the account (password
120
120
  resets, invites, billing) — are not a workspace's and are not limited. A new
121
121
  value or a new site binding keeps the limit. Limiting a secret seals the list
122
122
  with the value, like `sites` (see [How they are kept](#how-they-are-kept)),
@@ -252,7 +252,7 @@ secrets: GA_KEY materialised in the sandbox for bash; DATAFORSEO_PASSWORD bound
252
252
  ## Connected accounts
253
253
 
254
254
  Some third parties are connected rather than pasted — Google, GitHub,
255
- anything OAuth. Settings → Connections walks the consent flow once and stores
255
+ anything OAuth. Settings → Secrets → Connections walks the consent flow once and stores
256
256
  the result as an `oauth2` secret; the platform refreshes it. An agent names
257
257
  it in `secrets:` like any other.
258
258
 
package/docs/security.md CHANGED
@@ -268,7 +268,7 @@ run whose charge has not yet been recorded is kept until it is. `0` keeps a
268
268
  record for ever. An install without a database keeps its audit log in a
269
269
  file, numbered by line, and does not prune it.
270
270
 
271
- Closing the account (Settings → Account) suspends it at once and tells the
271
+ Closing the account (Settings → General → Close this account) suspends it at once and tells the
272
272
  platform team, who settle the last invoice and delete the account's data:
273
273
  its records, files, keys and sessions. The ledger and the audit entry that
274
274
  says it was deleted are kept. Backups are their own matter:
@@ -111,7 +111,7 @@ edit `~/foldrun/.env` and run `docker compose up -d` there.
111
111
  | `FOLDRUN_PUBLIC_URL` | `http://localhost:3900` | the address people open. CLI sign-in, approve links, password resets and shares are made with it |
112
112
  | `FOLDRUN_BIND` | `127.0.0.1` | where the dashboard listens. The default is this machine only — reach it over an SSH tunnel or a reverse proxy. `0.0.0.0` opens it to the network: sign up straight away, because the first account becomes the owner |
113
113
  | `FOLDRUN_VERSION` | the current `stable` | a version to pin, `vYYYY.MM.DD.N`; `stable` unpins. Give it to the installer: in `.env` by hand it holds only with `FOLDRUN_PINNED=yes` beside it, or the next installer run moves it to `stable` |
114
- | `ANTHROPIC_API_KEY` | none | the install's model key. Without one, each account adds its own in Settings → Model; a step with neither is refused with what to set |
114
+ | `ANTHROPIC_API_KEY` | none | the install's model key. Without one, each account adds its own in Settings → Models; a step with neither is refused with what to set |
115
115
  | `FOLDRUN_DIR` | `~/foldrun` | where the install lives (installer only) |
116
116
  | `FOLDRUN_DOCKER_SOCK` | `/var/run/docker.sock` | the Docker socket; rootless Docker is found by the installer |
117
117
  | `FOLDRUN_SETUP_TOKEN` | made once | the first account (the owner) is created only with this, through the printed `/signup?setup=…` link |
@@ -107,7 +107,7 @@ and yours now, in the workspaces both allow; a key is never an owner, so an
107
107
  owner's sign-in here is an admin, and inviting, changing or removing an admin
108
108
  stays in Settings → Team. The audit log marks each such act `via: foldrun
109
109
  login`. Transferring the account, your password, email, two-step sign-in and
110
- sessions stay in the browser. Any other key — one made in Settings → API
110
+ sessions stay in the browser. Any other key — one made in Settings → API keys → API
111
111
  keys, a CI key — is refused all of these.
112
112
  A scoped admin sees and revokes only keys inside its own scope; a key wider
113
113
  than that, the owner's included, is not in its list.
@@ -215,7 +215,7 @@ to the next level with one line in the trace rather than failing the step.
215
215
 
216
216
  When something is going wrong — an agent posting what it should not, a
217
217
  loop spending money — pause the workspace, or the whole account, from its
218
- Settings → Governance → Pause, `foldrun workspace pause` / `foldrun account pause`, or
218
+ Settings → Policies → Pause runs, `foldrun workspace pause` / `foldrun account pause`, or
219
219
  the API (`POST /api/workspaces/<ws>/pause`, `POST /api/account/pause`).
220
220
 
221
221
  While paused, nothing new starts: a schedule's fire, a webhook delivery, a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "19.2.1",
3
+ "version": "19.2.3",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
package/src/commands.mjs CHANGED
@@ -2644,7 +2644,7 @@ async function remoteCall(url, flags, apiPath, init = {}, { seconds } = {}) {
2644
2644
  function rateLimitHint(res, body) {
2645
2645
  const after = body?.retry_after ?? res.headers.get("retry-after");
2646
2646
  const limit = res.headers.get("x-ratelimit-limit");
2647
- return ` — rate limited${limit ? ` (${limit} a minute)` : ""}; already waited once${after ? `, try again in ${after}s` : ""}. Settings → API shows this account's limits`;
2647
+ return ` — rate limited${limit ? ` (${limit} a minute)` : ""}; already waited once${after ? `, try again in ${after}s` : ""}. Settings → API keys → API shows this account's limits`;
2648
2648
  }
2649
2649
 
2650
2650
  /** The glyph an event leads with: a fault, a tool, or a plain line. */
@@ -3350,7 +3350,7 @@ async function secretWorkspacesCmd(args, flags, url, layout) {
3350
3350
  }
3351
3351
  const workspaces = flags.all === true ? null : flags.none === true ? [] : named;
3352
3352
  // --if-workspaces a,b (or all, or none): the list read before. Refused (409)
3353
- // when another admin changed it since, as Settings → Connections does.
3353
+ // when another admin changed it since, as Settings → Secrets → Connections does.
3354
3354
  /** @type {{ ifWorkspaces?: string[] | null }} */
3355
3355
  const guard = {};
3356
3356
  if (flags["if-workspaces"] !== undefined) {
@@ -3372,7 +3372,7 @@ function siteFlags(flags) {
3372
3372
  }
3373
3373
 
3374
3374
  /**
3375
- * Whether the far end still accepts a secret, as Settings → Connections says
3375
+ * Whether the far end still accepts a secret, as Settings → Secrets → Connections says
3376
3376
  * it: accepted, refused (with when it last worked), the host's own failure,
3377
3377
  * or never used — which is not the same as working.
3378
3378
  */
@@ -5020,7 +5020,7 @@ async function sourceShare(url, flags, ws, base, spec) {
5020
5020
  // The route's own 404 says "no <path> in <ws>"; any other 404 is a
5021
5021
  // platform from before the route.
5022
5022
  if (err instanceof HttpError && err.status === 404 && !/^no /.test(err.message)) {
5023
- throw new Error(`${url} has no "Move to shared" route yet — it is newer than this platform; move it in Settings → the workspace's assets, or update the platform`);
5023
+ throw new Error(`${url} has no "Move to shared" route yet — it is newer than this platform; move it on the dashboard (the workspace's Files or Tools & hooks page → Move to shared), or update the platform`);
5024
5024
  }
5025
5025
  throw err;
5026
5026
  }
@@ -11562,7 +11562,7 @@ function computeText(p, none) {
11562
11562
  /**
11563
11563
  * `foldrun usage compute` — the cores and GiB the account's running steps
11564
11564
  * may hold together and in one step, what they hold now, and the steps
11565
- * waiting for room (Settings → Governance, GET /api/usage/compute).
11565
+ * waiting for room (Settings → Policies → Governance, GET /api/usage/compute).
11566
11566
  */
11567
11567
  async function usageComputeCmd(flags) {
11568
11568
  const url = platformFor(flags, "usage compute");
@@ -13136,7 +13136,7 @@ async function libraryCmd(positional, flags) {
13136
13136
 
13137
13137
  /**
13138
13138
  * `foldrun secrets clients [add <name> | rm <name>]` — the OAuth apps saved on
13139
- * the platform (Settings → Connections), which a consent runs from without
13139
+ * the platform (Settings → Secrets → Connections), which a consent runs from without
13140
13140
  * anyone typing a client id again. The client secret is never shown.
13141
13141
  */
13142
13142
  async function oauthClientsCmd(positional, flags) {
@@ -13461,7 +13461,7 @@ async function billingPlansCmd(verb, sub, flags) {
13461
13461
  }
13462
13462
 
13463
13463
  /**
13464
- * `foldrun api version [pin <YYYY-MM-DD> | unpin]` — Settings → API: the API
13464
+ * `foldrun api version [pin <YYYY-MM-DD> | unpin]` — Settings → API keys → API: the API
13465
13465
  * version this account's requests get when they send no Foldrun-Version, the
13466
13466
  * versions still served, and the rate limits.
13467
13467
  */
@@ -13837,7 +13837,7 @@ async function teamRemoveCmd(positional, flags) {
13837
13837
  * <zone|auto>` the zone timestamps and crons are read in (POST
13838
13838
  * /api/auth/timezone). Only a `foldrun login` key is a person; a key made by
13839
13839
  * hand is refused. Password, email, two-step sign-in and sessions stay in
13840
- * Settings → Profile.
13840
+ * Profile.
13841
13841
  */
13842
13842
  async function meCmd(positional, flags) {
13843
13843
  const url = remoteUrl(flags);
@@ -13873,7 +13873,7 @@ async function meCmd(positional, flags) {
13873
13873
  console.log(` account ${me.account}`);
13874
13874
  console.log(` role ${me.role}${me.actor?.kind === "key" ? c.dim(" (this machine's sign-in)") : ""}`);
13875
13875
  console.log(` timezone ${p.timezone ?? c.dim("automatic (the browser's)")}`);
13876
- console.log(`\n ${c.dim("foldrun me name <first> [last] · foldrun me timezone <zone|auto> · password, email, two-step sign-in: Settings → Profile")}\n`);
13876
+ console.log(`\n ${c.dim("foldrun me name <first> [last] · foldrun me timezone <zone|auto> · password, email, two-step sign-in: Profile")}\n`);
13877
13877
  return 0;
13878
13878
  }
13879
13879