foldrun 19.2.2 → 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/api-usage.md +3 -3
- package/docs/budgets-and-billing.md +9 -9
- package/docs/checks.md +2 -2
- package/docs/cli.md +4 -4
- package/docs/faq.md +1 -1
- package/docs/four-jobs.md +4 -4
- package/docs/getting-started.md +1 -1
- package/docs/mcp.md +1 -1
- package/docs/network.md +1 -1
- package/docs/notifications.md +1 -1
- package/docs/oauth.md +1 -1
- package/docs/providers.md +3 -3
- package/docs/runs.md +2 -2
- package/docs/secrets.md +2 -2
- package/docs/security.md +1 -1
- package/docs/self-hosting.md +1 -1
- package/docs/team-and-access.md +1 -1
- package/docs/workspaces.md +1 -1
- package/package.json +1 -1
- package/src/commands.mjs +9 -9
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 →
|
|
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
|
-
|
|
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 →
|
|
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
|
|
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.
|
|
@@ -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 →
|
|
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
|
|
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 →
|
|
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
|
package/docs/getting-started.md
CHANGED
|
@@ -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 →
|
|
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 → **
|
|
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
|
|
package/docs/notifications.md
CHANGED
|
@@ -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 →
|
|
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 →
|
|
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 →
|
|
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 →
|
|
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 →
|
|
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 →
|
|
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 →
|
|
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:
|
package/docs/self-hosting.md
CHANGED
|
@@ -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 →
|
|
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 |
|
package/docs/team-and-access.md
CHANGED
|
@@ -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.
|
package/docs/workspaces.md
CHANGED
|
@@ -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 →
|
|
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
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
|
|
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
|
-
*
|
|
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:
|
|
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
|
|