foldrun 9.0.3 → 10.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/bin/foldrun.mjs +6 -2
- package/docs/api.md +66 -52
- package/docs/checks.md +27 -1
- package/docs/cli.md +4 -4
- package/docs/flows.md +1 -1
- package/docs/notifications.md +10 -1
- package/docs/runs.md +3 -1
- package/docs/secrets.md +51 -0
- package/docs/security.md +32 -5
- package/docs/storage-and-sharing.md +21 -1
- package/docs/team-and-access.md +24 -3
- package/package.json +2 -2
- package/src/commands.mjs +139 -25
package/bin/foldrun.mjs
CHANGED
|
@@ -155,7 +155,7 @@ const HELP = `foldrun — agents are just folders
|
|
|
155
155
|
foldrun runs what has run lately, across the account — --status, --verdict, --outcome (good, done, quiet, blocked, bad, failed, needs-you, …), --since, --to, --limit; search with --tool, --tool-error, --agent, --model, --min-tokens 50k, --min-secs, or --view <name>
|
|
156
156
|
foldrun runs views your saved run searches (--local prints exactly what logs --local prints)
|
|
157
157
|
foldrun runs doctor <run-id> the run doctor: the assistant reads a failed run and the files it names, says why (platform, check, work or outside) and proposes the fix as diffs, saved on yes (--to, --yes, --dry-run, --json)
|
|
158
|
-
foldrun runs rm <run-id> delete a run's record and archived outputs; a live one is stopped first — asks first, --yes means it
|
|
158
|
+
foldrun runs rm <run-id> delete a run's record and archived outputs (an admin); a live one is stopped first — asks first, --yes means it
|
|
159
159
|
foldrun report <run-id> one run, whole: header, every step, what it wrote and what is still waiting
|
|
160
160
|
foldrun report <run-id> get <agent>/<path> download a file the run archived from that agent's outputs/ (--file <path>|-, --force)
|
|
161
161
|
foldrun report <run-id> --compare [<run-id>] beside the flow's last good run (or the one named): changed files and what differs step by step (--json)
|
|
@@ -217,6 +217,7 @@ const HELP = `foldrun — agents are just folders
|
|
|
217
217
|
foldrun backups requests every restore asked of the platform team, and where each stands (--json)
|
|
218
218
|
foldrun secrets set NAME store a secret (prompted, never echoed) — also ls, rm, status; --kind file|ssh|api|service-account|m2m for the other shapes; --site <domain> (repeatable) binds it as it is stored
|
|
219
219
|
foldrun secrets sites NAME [site…] bind a secret to sites: the egress proxy fills it for those alone and it never enters a sandbox; no sites lists them, --clear unbinds
|
|
220
|
+
foldrun secrets workspaces NAME [workspace…] limit an account secret to those workspaces — every other one finds it not set; --all opens it to every workspace again, --none to no workspace, no names shows which may use it (an admin over every workspace; applies to runs that start after it)
|
|
220
221
|
foldrun secrets clients the OAuth clients saved on the platform — also add <name> (--authorize-url/--token-url, --client-id, --scopes, --authorize-param name=value), rm <name>
|
|
221
222
|
foldrun connect NAME OAuth sign-in from the terminal, stored as an auto-refreshing secret — --client <saved> runs it from a saved client through the platform
|
|
222
223
|
foldrun deploy [dir] push the whole account, or deploy <workspace> for one of them
|
|
@@ -339,6 +340,9 @@ Options
|
|
|
339
340
|
--value "<text>" secrets set: skip the prompt (careful with shell history)
|
|
340
341
|
--site <domain> secrets set, secrets sites: a site the secret is bound to — the egress proxy fills it for those alone (repeatable, or a,b)
|
|
341
342
|
--clear secrets sites: unbind it; flow compute: no cap of its own
|
|
343
|
+
--all secrets workspaces: every workspace may use the account secret again
|
|
344
|
+
--none secrets workspaces, secrets set: no workspace may use the account secret
|
|
345
|
+
--workspaces <a,b> secrets set: store an account secret limited to those workspaces, in the same write (with --account)
|
|
342
346
|
--add <site> agent network: add a site to its network: list (repeatable)
|
|
343
347
|
--remove <site> agent network: take a site off its network: list (repeatable)
|
|
344
348
|
--out <file> api spec: where to write the OpenAPI document (default: stdout); check: where to write the JSON or SARIF report
|
|
@@ -406,7 +410,7 @@ if (!command || command === "--help" || command === "-h") {
|
|
|
406
410
|
// `--value` as the account's argument and stored an empty secret; `--force
|
|
407
411
|
// ./dir` swallowed the directory. A flag followed by another flag is also
|
|
408
412
|
// boolean, so an unlisted switch at least does not eat its neighbour.
|
|
409
|
-
const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine"]);
|
|
413
|
+
const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none"]);
|
|
410
414
|
// Flags said more than once collect into a list: `--tag a --tag b`.
|
|
411
415
|
const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param"]);
|
|
412
416
|
// `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
|
package/docs/api.md
CHANGED
|
@@ -66,17 +66,17 @@ api workspaces/$WS/flows/publish/run -X POST # start a flow
|
|
|
66
66
|
|
|
67
67
|
| Route | Methods | |
|
|
68
68
|
|---|---|---|
|
|
69
|
-
| `/api/workspaces` | GET, POST | list; create (`name`, plus one of: `template: true` — blank, just an AGENTS.md, what the dashboard sends; `starter: true` — the example researcher, writer and publish flow; `demo: true`; `files`). A POST to a name that exists deploys over it
|
|
70
|
-
| `/api/workspaces/<ws>` | GET, PATCH, DELETE | read; rename or re-describe (`name`, `description`), or set its defaults (`timezone`, `budget`, `compute` — `{ vcpu, memGiB, diskGiB }`, this workspace's own pool, merged over what is set —, `notify`, `network_enforce`, `owner`, `alerts`, `judge` — null clears one, edited in AGENTS.md in place; keys only the account may set are ignored); delete |
|
|
69
|
+
| `/api/workspaces` | GET, POST | list; create (`name`, plus one of: `template: true` — blank, just an AGENTS.md, what the dashboard sends; `starter: true` — the example researcher, writer and publish flow; `demo: true`; `files`). A POST to a name that exists deploys over it, through the deploy's gate — files that do not check out, or a run still reading the workspace, are `422` with `issues`/`blockedBy` and nothing changes, and it is audited as `workspace.deployed`; add `ifAbsent: true` to create only — a name that exists is then `409` and nothing changes, decided atomically (the assistant's Create workspace and `foldrun assistant` send it) |
|
|
70
|
+
| `/api/workspaces/<ws>` | GET, PATCH, DELETE | read; rename or re-describe (`name`, `description` — written as one YAML value and recorded in History), or set its defaults (`timezone`, `budget`, `compute` — `{ vcpu, memGiB, diskGiB }`, this workspace's own pool, merged over what is set —, `notify`, `network_enforce`, `owner`, `alerts`, `judge` — null clears one, edited in AGENTS.md in place; keys only the account may set are ignored); delete — its stored files and public links go with it, as a rename moves them. An account secret limited to it ([limited to some workspaces](secrets#limited-to-some-workspaces)) follows a rename and loses it on a delete, done before the folder moves or goes: 409 naming any such secret the platform's keys cannot read (nothing renamed or deleted), 503 when the vault cannot be updated; a rename onto a name that exists is 409 |
|
|
71
71
|
| `/api/workspaces/<ws>/pause` | GET, POST, DELETE | the workspace's kill switch. GET `{ paused, account, workspace }` — what holds runs here (`paused` is the one that applies, `scope` saying whose), each `{ at, by, reason? }` or null. POST `{ reason?, stop?: true }` pauses: every start here — schedule, webhook, chained flow, a person's Run, a rerun — is refused `423` with who paused it, and a refused trigger is logged as `halted`; A run queued before the pause and not yet begun waits until the resume. `stop: true` also stops every running, queued and parked run (needs `run:start`) and answers `stopped` and `failed`. DELETE resumes. Needs `workspace:manage`. The account's pause holds here too and only the account's DELETE lifts it; an operator's suspension is separate and neither lifts it |
|
|
72
|
-
| `/api/workspaces/<ws>/vocabulary` | GET | which document kinds this workspace admits — its `docs` list is what `[[ ]]` resolves: knowledge, memory, `state/` and `storage/` files, plus the folders themselves |
|
|
73
|
-
| `/api/workspaces/<ws>/check` | GET | what `foldrun check` says about the deployed copy, as findings with rule ids — what a deploy refuses or warns about, and the scanner's secret, hidden-text, agent-risk and supply-chain rules ([Checks](checks)). `?security=1` keeps the security rules, `?rule=<id or category>` (repeatable) one, `?online=1` adds the network checks (known vulnerabilities, remote MCP tool text); `{ counts, findings: [{ rule, level, file, line, message, fingerprint }], rules, online?: { problems, sources }, rescan: { checkedAt, findings, pending, problems } | null }`. Read-only, no model call |
|
|
72
|
+
| `/api/workspaces/<ws>/vocabulary` | GET | which document kinds this workspace admits — its `docs` list is what `[[ ]]` resolves: knowledge, memory, `state/` and `storage/` files, plus the folders themselves. `secrets` names the workspace's secrets and, to a caller with every workspace, the account's (as `GET /api/secrets` lists them). `404` when the workspace does not exist |
|
|
73
|
+
| `/api/workspaces/<ws>/check` | GET | what `foldrun check` says about the deployed copy, as findings with rule ids — what a deploy refuses or warns about, and the scanner's secret, hidden-text, agent-risk and supply-chain rules ([Checks](checks)). `?security=1` keeps the security rules, `?rule=<id or category>` (repeatable) one, `?online=1` adds the network checks (known vulnerabilities, remote MCP tool text) — editor and above, since they send the server out to OSV and the workspace's MCP servers; the answer is kept for 10 minutes while the files are unchanged, and a workspace gets six fresh online passes per 10 minutes (then `429` with `Retry-After`); `{ counts, findings: [{ rule, level, file, line, message, fingerprint }], rules, online?: { problems, sources }, rescan: { checkedAt, findings, pending, problems } | null }`. Read-only, no model call |
|
|
74
74
|
|
|
75
75
|
## Source — the files themselves
|
|
76
76
|
|
|
77
77
|
| Route | Methods | |
|
|
78
78
|
|---|---|---|
|
|
79
|
-
| `/api/workspaces/<ws>/source?path=` | GET, PUT, PATCH, DELETE | GET: one file (`{ path, content, sha256 }`), or the tree with no `path`. PUT `{path, content, message?, ifMatch?, check?}` writes one file (a revision, `message` its note) and answers `{ ok, path, sha256, issues }`, the deploy's checks for that file as saved. With `check: true` (what the dashboard editor sends) a file with an error a deploy would refuse is refused with `422` and the `issues`, nothing written; warnings never refuse; with `ifMatch` — the `sha256` a GET returned — it is refused with `409` and nothing written if the file has changed since; `ifMatch: null` says the caller saw no file there, and is refused the same way once one exists (History's restore and the AI draft's save send it, the draft's new files as `null`). PATCH `{from, to}` moves one. DELETE `{path}` removes a file or folder. The body carries the path on writes — a `?path=` there is a `400` |
|
|
79
|
+
| `/api/workspaces/<ws>/source?path=` | GET, PUT, PATCH, DELETE | GET: one file (`{ path, content, sha256 }`), or the tree with no `path`. PUT `{path, content, message?, ifMatch?, check?}` writes one file (a revision, `message` its note) and answers `{ ok, path, sha256, issues }`, the deploy's checks for that file as saved. With `check: true` (what the dashboard editor sends) a file with an error a deploy would refuse is refused with `422` and the `issues`, nothing written; warnings never refuse; with `ifMatch` — the `sha256` a GET returned — it is refused with `409` and nothing written if the file has changed since; `ifMatch: null` says the caller saw no file there, and is refused the same way once one exists (History's restore and the AI draft's save send it, the draft's new files as `null`). PATCH `{from, to}` moves one. DELETE `{path}` removes a file or folder. A write names a workspace that exists — to one that does not it is `404`, and nothing is made (make it with `POST /api/workspaces`, a deploy or an import); the same holds for every route that writes a file: agents, evals, flows, assets, settings. The body carries the path on writes — a `?path=` there is a `400`. A change to a policy key of the workspace's `AGENTS.md` (`budget`, `compute`, `notify`, `network_enforce`, `telemetry`, `alerts`, `owner`, `judge`, `timezone`) needs `workspace:manage` — `403` naming the key, nothing written ([Team and access](team-and-access#a-workspaces-policy-is-an-admins)) |
|
|
80
80
|
| | PUT | write (`path`, `content`, optional `message` — recorded on the revision, as `foldrun source put --message` sends it) |
|
|
81
81
|
| | PATCH | move (`from`, `to`) |
|
|
82
82
|
| | DELETE | remove (`path`) |
|
|
@@ -101,6 +101,15 @@ Returns `{ ok, applied, commit, added, updated, removed, preserved }`; with `dry
|
|
|
101
101
|
is declarative, so the whole of it is checked before any of it goes live: a
|
|
102
102
|
broken flow is caught at push time rather than at 3am when its schedule fires.
|
|
103
103
|
|
|
104
|
+
A deploy to a name with no workspace yet makes one, so it needs what making
|
|
105
|
+
one needs anywhere: the `admin` role (`workspace:manage`), and on a hosted
|
|
106
|
+
plan room under its workspace count (`402` otherwise) — as `POST
|
|
107
|
+
/api/workspaces` and an import of a workspace package. A deploy to a workspace
|
|
108
|
+
that exists needs `editor`. `commit` is a commit id (letters, digits, `.`, `_`,
|
|
109
|
+
`@`, `-`, at most 121 characters), `400` before anything is written otherwise;
|
|
110
|
+
it names the deploy's revision the first time it is deployed, and a later
|
|
111
|
+
deploy of the same commit is recorded under its own id with that `commit`.
|
|
112
|
+
|
|
104
113
|
`dryRun: true` checks and changes nothing. `force: true` deploys over a live
|
|
105
114
|
run, which otherwise refuses — swapping files under a running flow means step 3
|
|
106
115
|
reads agents step 1 never saw.
|
|
@@ -118,8 +127,8 @@ agent wrote that the push does not mention.
|
|
|
118
127
|
|
|
119
128
|
| Route | Methods | |
|
|
120
129
|
|---|---|---|
|
|
121
|
-
| `/api/workspaces/<ws>/deploy` | POST | deploy the whole workspace from a list of files — checked as a whole first, refused with `422` and `issues` when it does not check out. `dryRun`, `force`, `expectRemoved` below. Idempotent |
|
|
122
|
-
| `/api/workspaces/<ws>/runtimes` | GET | the `runtime:` builds a deploy started, each with its `state` — below |
|
|
130
|
+
| `/api/workspaces/<ws>/deploy` | POST | deploy the whole workspace from a list of files — checked as a whole first, refused with `422` and `issues` when it does not check out. `dryRun`, `force`, `expectRemoved` below. A change to a policy key of the workspace's `AGENTS.md` (`budget`, `compute`, `notify`, `network_enforce`, `telemetry`, `alerts`, `owner`, `judge`, `timezone`) needs `workspace:manage` — `403` naming the key, nothing written ([Team and access](team-and-access#a-workspaces-policy-is-an-admins)); a dry run is not refused. Idempotent |
|
|
131
|
+
| `/api/workspaces/<ws>/runtimes` | GET | the `runtime:` builds a deploy started, each with its `state` — below. `404` when the workspace does not exist |
|
|
123
132
|
|
|
124
133
|
`GET /api/workspaces/<ws>/runtimes` answers what a deploy started on the
|
|
125
134
|
platform: every distinct `runtime:` the workspace's agents need
|
|
@@ -134,7 +143,7 @@ installer's `error`, its cause on the first line. `foldrun deploy` polls it afte
|
|
|
134
143
|
| Route | Methods | |
|
|
135
144
|
|---|---|---|
|
|
136
145
|
| `/api/workspaces/<ws>/flows` | GET, POST | list; create (`name`, `pattern`) |
|
|
137
|
-
| `/api/workspaces/<ws>/flows/<flow>` | POST, PATCH, DELETE | edit a step (`step`, `instruction`, `options`, `target`, `subflow`), rearrange (`groups`), set `trigger`, set `compute` (`{ vcpu, memGiB, diskGiB }` or `null` — what one run may hold at once, merged over what the flow says), a canvas edit (`edit`, `edits`), undo (`restore` + `expect`); delete. Every PATCH and DELETE takes `expect` — the text the step numbers were read from, or its sha256 — and is refused with `409` and the current `text`, nothing written, when the file no longer reads it (the canvas, the list view's board and step options, and the CLI's `flow add`/`rm-step`/`dup-step --to` send it; the dashboard shows the 409 as "this flow changed since you opened it — reload") |
|
|
146
|
+
| `/api/workspaces/<ws>/flows/<flow>` | POST, PATCH, DELETE | edit a step (`step`, `instruction`, `options`, `target`, `subflow`), rearrange (`groups`), set `trigger`, set `compute` (`{ vcpu, memGiB, diskGiB }` or `null` — what one run may hold at once, merged over what the flow says), a canvas edit (`edit`, or `edits` — at most 200 in one request, `400` past that), undo (`restore` + `expect`); delete. Every PATCH and DELETE takes `expect` — the text the step numbers were read from, or its sha256 — and is refused with `409` and the current `text`, nothing written, when the file no longer reads it (the canvas, the list view's board and step options, and the CLI's `flow add`/`rm-step`/`dup-step --to` send it; the dashboard shows the 409 as "this flow changed since you opened it — reload") |
|
|
138
147
|
| `/api/workspaces/<ws>/flows/draft` | POST, PATCH, DELETE | POST draft a flow with a model: `{ description, flow? }` (`flow` redrafts that one). Returns `{ ok, files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], repaired, notes }` — checked with the deploy's checks and the flow lint, repaired once. **Writes nothing**; save with the source PUT. Needs `workspace:write`; a description over 4,000 characters is `413`; a Chat-Completions `provider:` is `422`. On the platform's models the balance is checked first (`402`) and the call is charged as one ledger line, flow `ai-draft`. PATCH and DELETE, and a POST without `description`, are the edits of a flow that happens to be named `draft`, exactly as at `flows/<flow>` |
|
|
139
148
|
| `/api/workspaces/<ws>/flows/<flow>/run` | POST | start it. An `Idempotency-Key` header, or `idempotencyKey` in the body, makes a retried call safe: a dropped response, a proxy timeout or a CI step that ran twice is answered `started: false` with the `runId` it already started, rather than starting a second run and billing for it. Keys are remembered for 24 hours, per flow |
|
|
140
149
|
| `/api/workspaces/<ws>/flows/<flow>/filter` | POST | test the flow's `filter:` against a delivery without starting anything: `{ payload }` — a webhook's JSON body (or the body as a string, read as JSON), an email's `{ from, to, subject, text }`, a chained run's `{ run, flow, status, ending, verdict, summary }`, a storage event's `{ by, paths }`. Answers `{ flow, trigger, filter, applies, match, reason }` — `reason` names the first condition that failed; a flow with no filter matches everything. Reads the deployed flow; nothing is recorded or charged |
|
|
@@ -178,14 +187,14 @@ history with each message.
|
|
|
178
187
|
| `/api/workspaces/<ws>/agents/<agent>` | PATCH | edit one line of an agent's frontmatter in place, as the flow canvas does: `{ list: { key, name, action } }` — `key` one of `subagents`, `agents`, `tools`; `action` `add` or `remove` — or `{ set: { key: "description" | "sandbox", value } }` (`sandbox` takes `own` or `parent`, else 400), or `{ network }` — the sites its sandbox may reach: `"open"`, `"trusted"`, `"none"`, a list of sites, or `{ level, allow, defaults }`; `null` removes the line so it inherits ([Network](network)). A `network` nobody could read is a 400 that says why. Only that key's lines change — comments, key order and prose stay. Answers `{ ok, changed }`; 404 for an unknown agent. `workspace:write` |
|
|
179
188
|
| `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run) |
|
|
180
189
|
| `/api/workspaces/<ws>/agents/import` | GET, POST | copy an agent in from another workspace of the account. GET lists what could be imported (every other workspace you can read, with its agents). POST `{ from, agent, as? }` copies `agents/<agent>/` — its agent.md and own skills/, scripts/, knowledge/; never memory/, outputs/, state/ — and answers `{ name, files, warnings }`; `warnings` names tools, skills, scripts and secrets the copy uses that this workspace lacks. 409 on a name clash (pass `as`), 404 for an unknown workspace or agent, 403 when `from` is outside your key's scope. Idempotent |
|
|
181
|
-
| `/api/workspaces/<ws>/proposals` | GET | the workspace's proposed fixes, newest first: `{ proposals: [{ id, workspace, eval, by (auto, or who asked), createdAt, updatedAt, status, failures: [{ runId?, case?, check, detail, at }], jobId, reply (the assistant's reasoning), files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], error?, notes?, decidedBy?, decidedAt?, applied? }] }`. `status` is `drafting`, `ready`, `failed`, `applying`, `applied`, `partial` (a write failed part-way; `applied` names what was written) or `dismissed`. `?status=`, `?eval=`. A drafting one is settled as it is read |
|
|
190
|
+
| `/api/workspaces/<ws>/proposals` | GET | the workspace's proposed fixes, newest first (`404` when the workspace does not exist): `{ proposals: [{ id, workspace, eval, by (auto, or who asked), createdAt, updatedAt, status, failures: [{ runId?, case?, check, detail, at }], jobId, reply (the assistant's reasoning), files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], error?, notes?, decidedBy?, decidedAt?, applied? }] }`. `status` is `drafting`, `ready`, `failed`, `applying`, `applied`, `partial` (a write failed part-way; `applied` names what was written) or `dismissed`. `?status=`, `?eval=`. A drafting one is settled as it is read |
|
|
182
191
|
| `/api/workspaces/<ws>/proposals/<id>` | GET, POST | one proposal. `POST { action: "apply" }` writes its files, each a revision by the caller, only when every one still reads what it was drawn against (`409` naming the file that changed) and can be written (`422`; a check error the deploy would refuse is `422` too); `POST { action: "dismiss" }` sets it aside — its failures stay looked at. Only agents, flows and skills are ever in one. Needs `workspace:write` |
|
|
183
192
|
| `/api/workspaces/<ws>/export` | GET | this workspace, one flow or one agent as a `.zip` — `?kind=flow&name=<flow>` (the flow, every flow it runs as a step, every agent those steps and their colleagues name, and the workspace tools, skills and scripts they grant), `?kind=agent&name=<agent>` (its folder and what it grants), or neither for the whole authored tree. Never memory/, state/, outputs/, storage, runs or a secret's value; `foldrun-package.json` inside says what it is. Any role that can read the workspace |
|
|
184
|
-
| `/api/workspaces/<ws>/import` | POST | take a package in; the body is the `.zip` (`content-type: application/zip`, at most 20 MB). `?dryRun=1` answers `{ kind, name, from, creates, added, overwritten, unchanged, needs: { secrets, tools, skills, scripts, agents, flows } }` plus `skipped` (entries it will not write: memory, state, anything outside the authored folders) and writes nothing. Without it, applies as one revision; 409 when it would replace a file with different text unless `?overwrite=1`, or when a file cannot be written there (all or nothing). Never deletes. A `Content-Length` is required (411 without). A workspace package into a name that does not exist makes that workspace (`workspace:manage`, the plan's workspace count). 400 for anything not a package, or one holding memory/, state/ or outputs/. Idempotent |
|
|
193
|
+
| `/api/workspaces/<ws>/import` | POST | take a package in; the body is the `.zip` (`content-type: application/zip`, at most 20 MB). `?dryRun=1` answers `{ kind, name, from, creates, added, overwritten, unchanged, needs: { secrets, tools, skills, scripts, agents, flows } }` plus `skipped` (entries it will not write: memory, state, anything outside the authored folders) and writes nothing. Without it, applies as one revision; 409 when it would replace a file with different text unless `?overwrite=1`, or when a file cannot be written there (all or nothing). Never deletes. A `Content-Length` is required (411 without). A workspace package into a name that does not exist makes that workspace (`workspace:manage`, the plan's workspace count). 400 for anything not a package, or one holding memory/, state/ or outputs/. A change to a policy key of the workspace's `AGENTS.md` (`budget`, `compute`, `notify`, `network_enforce`, `telemetry`, `alerts`, `owner`, `judge`, `timezone`) needs `workspace:manage` — `403` naming the key, nothing written ([Team and access](team-and-access#a-workspaces-policy-is-an-admins)). Idempotent |
|
|
185
194
|
| `/api/workspaces/<ws>/evals` | GET, POST | list; create (`name`) |
|
|
186
195
|
| `/api/workspaces/<ws>/evals/<eval>/run` | GET, POST | POST runs one eval and answers with its result; with `{ async: true }` it answers `202 { started, eval, runId, startedAt }` at once and the eval runs on — an eval of slow cases outlives a proxy's read timeout (Cloudflare's is 125 s by default). One run of an eval at a time: a second is `409` naming the run that holds it. `GET ?run=<runId>` is what to poll — that run alone, whatever else runs or writes the eval's latest result meanwhile: `{ runId, state, running }` where `state` is `running`, `done` (with its `result`), `failed` (with `error`), `lost` (it stopped reporting before saving a result, e.g. a restart) or `unavailable` (an id not on record — the last 20 runs are kept). Plain `GET` answers who holds the eval now (`running`, `runId`, `startedAt`) and the latest `result`. The dashboard and `foldrun eval --to` start async and poll by run id |
|
|
187
|
-
| `/api/workspaces/<ws>/evals/<eval>/compare` | GET, POST | compare models on one eval: its cases under two to four settings, side by side. `POST { configs: [{ model, effort?, agent? }], repeat?, maxUsd? }` — `model` a tier (`fast`, `default`, `max`) or a model id; `effort` low…max; `agent` (flow evals) forces only that agent's steps, else every step; `repeat` 1–5 (1); `maxUsd` the spend limit, above 0 and at most 100 (5). At most 60 runs (cases × settings × repeat, else `413`). Answers `202 { started, eval, runId, startedAt, trials, maxUsd }` and runs on: every run a test run, the eval's own judge for all. `GET ?run=<runId>` → `{ runId, state, running }` — `running` (with `progress: { done, total }`), `done` (with `result`), `failed` (with `error`), `lost` or `unavailable`. `result` is `{ eval, target, judge, startedAt, finishedAt, repeat, maxUsd, spentUsd, stopped, configs: [{ model, effort, agent, label, trials, passed, notRun, rate, costUsd (runs and judges), judgeCostUsd, avgCostUsd, avgSecs (worker pick-up to end), runIds }], cases: [{ case, passed: [per setting], trials: [per setting] }] }`. Plain `GET` → `{ running, runId?, startedAt?, progress?, comparisons }` (the last 20, newest first). One comparison of an eval at a time (`409`); a grader, saved inputs or an eval with a `run:` check `400`. Needs `run:start` to start |
|
|
188
|
-
| `/api/workspaces/<ws>/evals/<eval>/improve` | POST | ask for a proposed fix now: for a grader, from its failed grades no proposal has covered; for an eval that runs cases, from its last result's failed cases. Answers `202` with the proposal, `status: "drafting"` — the assistant drafts it (one reply, paid as Ask AI's are); poll `GET …/proposals/<id>`. `409` when there is nothing to fix, a proposal for this eval is open, or the account or workspace is paused. Needs `run:start` |
|
|
196
|
+
| `/api/workspaces/<ws>/evals/<eval>/compare` | GET, POST | compare models on one eval: its cases under two to four settings, side by side. `POST { configs: [{ model, effort?, agent? }], repeat?, maxUsd? }` — `model` a tier (`fast`, `default`, `max`) or a model id; `effort` low…max; `agent` (flow evals) forces only that agent's steps, else every step; `repeat` 1–5 (1); `maxUsd` the spend limit, above 0 and at most 100 (5). At most 60 runs (cases × settings × repeat, else `413`). Answers `202 { started, eval, runId, startedAt, trials, maxUsd }` and runs on: every run a test run, the eval's own judge for all. `GET ?run=<runId>` → `{ runId, state, running }` — `running` (with `progress: { done, total }`), `done` (with `result`), `failed` (with `error`), `lost` or `unavailable`. `result` is `{ eval, target, judge, startedAt, finishedAt, repeat, maxUsd, spentUsd, stopped, configs: [{ model, effort, agent, label, trials, passed, notRun, rate, costUsd (runs and judges), judgeCostUsd, avgCostUsd, avgSecs (worker pick-up to end), runIds }], cases: [{ case, passed: [per setting], trials: [per setting] }] }`. Plain `GET` → `{ running, runId?, startedAt?, progress?, comparisons }` (the last 20, newest first). One comparison of an eval at a time (`409`), none while the account or workspace is paused (`409`); a grader, saved inputs or an eval with a `run:` check `400`. Needs `run:start` to start |
|
|
197
|
+
| `/api/workspaces/<ws>/evals/<eval>/improve` | POST | ask for a proposed fix now: for a grader, from its failed grades no proposal has covered; for an eval that runs cases, from its last result's failed cases. Answers `202` with the proposal, `status: "drafting"` — the assistant drafts it (one reply, paid as Ask AI's are); poll `GET …/proposals/<id>`. `409` when there is nothing to fix, a proposal for this eval is open, or the account or workspace is paused. Held to Ask AI's limits — the same per-person hourly count (`429`), and on the platform's models its daily account count (`429`) and the balance (`402`). Needs `run:start` |
|
|
189
198
|
| `/api/workspaces/<ws>/evals/<eval>/grades` | GET | a grader's grades (an eval with `trigger: runs`): `{ eval, flow, agent, sample, improve, days, summary, grades }`. `summary` is the window's `{ graded, passed, failed, errors, rate, costUsd, byDay: [{ day, graded, passed, failed }] }` (`rate` is passed ÷ decided, `null` when nothing was decided); `grades` the newest first, one per run — `{ eval, runId, flow, at, status (pass, fail or error — not decided), checks: [{ name, passed, error?, assertions: [{ type, value, passed, detail }] }], costUsd (the judges'), model, evalRevision, runRevision, runFinishedAt, by }`. `?days=` 1–90 (30), `?status=` pass, fail or error, `?limit=` 1–500 (100). An eval that runs cases is `400` |
|
|
190
199
|
| `/api/workspaces/<ws>/evals/<eval>/grade` | POST | grade one finished run now, sampled or not: `{ run }` → the grade (the shape above), kept like any other — the newest grade of a run is the one shown. Needs `run:start`; the judges run on the account's model key. A run that is not this grader's (another flow, or no step by its agent) is `400`, a run still going `409`, one with no reply to grade `409`, an eval that runs cases `400`, a paused account or workspace `409` |
|
|
191
200
|
| `/api/workspaces/<ws>/tools/<tool>/test` | POST | exercise one tool (`args`, `path`). An http tool with an `operations:` allowlist is probed only with a GET to one of its operations (no `path`: the first GET without parameters), and fails if the allowlist resolves nothing, as a run does |
|
|
@@ -203,12 +212,12 @@ paying for the steps around it.
|
|
|
203
212
|
| `/api/workspaces/<ws>/runs/<id>/calls/<call>` | GET | one tool call's recorded content (see [Runs](runs#what-a-run-records)): `{ call: { id, tool, input, output, inputChars, outputChars, truncated, inputCut, outputCut } }` — what it was given and what it gave back, secrets masked, each at most 65,536 characters; `inputChars`/`outputChars` are the whole length, `inputCut`/`outputCut` say which part was cut (`truncated`: either). `<call>` is the tool event's `call`; an event with `captured: true` has content here. 404 when nothing was recorded: the workspace says `capture: metadata`, or the run is from before 19 Oct 2026. A run's steps also carry `calls`, each model call (`n`, `at`, `ms`, `model`, `stop`, `tokens`, `tools`, and `subagent` / `attempt` when a sub-agent or a later attempt made it); a step that handed jobs to `sandbox: own` sub-agents carries `delegations` (`id`, `agent`, `status`, `costUsd`, `ms`), and each job is a step of its own with `subagentOf` (the delegating agent), `delegation` (that `id`) and `wrote` (the workspace paths it changed — copied into the delegating step's sandbox too, up to 4 MiB a job); and the run its `revision` (the workspace's latest revision when a worker picked it up — a deploy's commit, or the id an edit through `/source` was saved as) and `drivenAt` (when that was) |
|
|
204
213
|
| `/api/workspaces/<ws>/runs/<id>/trace` | GET | the run as one tree (see [Runs](runs#the-trace-tree)): `{ tree, failure }`. Each span is `{ id, kind, label, start, end, status, children, … }`, where `kind` is `run`, `step`, `model` (one model call: `model`, `stop`, `tokens`), `tool` (`call`, `captured` when its input and output were recorded) or `error` (`text`); `start`/`end` are epoch milliseconds and `status` is `ok`, `error`, `running`, `waiting`, `skipped` or `pending`. A tool call sits under the model call that asked for it. `failure` is the ids from the root to the first thing that went wrong, which the run page opens on; `[]` when nothing did |
|
|
205
214
|
| `/api/workspaces/<ws>/runs/<id>/compare?with=` | GET | this run beside another of the same flow (see [Runs](runs#compare-with-the-last-good-run)): `{ comparison: { base, run, revisionChanged, changedFiles, steps }, chosen }`. Each step is `{ step, agent, base, run, changes }`: both sides' status, instruction, model, seconds, tokens, model calls, tool counts, tool errors, first errors and first line said, and `changes` in words (`status: completed → failed`, `new error: …`, `instruction changed`, `tools: +web ×3`, `took 12s → 48s`, …). `changedFiles` lists the files changed between the revisions the two ran (null when one is unknown). `with` names the other run; unasked it is the newest earlier run of the flow that finished well, else the run this one re-ran (`chosen` says which) |
|
|
206
|
-
| `/api/workspaces/<ws>/runs/<id>` | GET, DELETE | the whole run: every step, its output, cost, timing, the runner `image` it ran on and — for a step that browsed through the account's pod from slim — its `browserPod` reconnects and fallback ([runs](runs#the-record)). `?wait=true&timeout=<s>` instead blocks until the run stops (or `timeout`, default 300, max 900) and answers the verdict the run routes give — `200` once the run has ended, however it ended: `ok: true` when it completed, `ok: false` with its `status` and `failure: { agent, reason }` when it failed or was stopped (a run that fails is the answer, not a fault in the call — it was a `500` before 29 Oct 2026); `202` still going (`timedOut`) or parked on a person (`awaitingApproval`). A start refused before any run exists — a paused account or workspace (`423`), an agent or flow that is not there (`404`), `overlap: skip` (`409`) — is answered as such and waits for nothing. Ask in short pieces: whatever sits in front of the platform cuts a request that stays silent too long (Cloudflare at 100 s, an AWS ALB at 60 s), and a flow can run for many minutes — the CLI's `--wait` asks 25 s at a time and comes back here on every `202` |
|
|
215
|
+
| `/api/workspaces/<ws>/runs/<id>` | GET, DELETE | the whole run: every step, its output, cost, timing, the runner `image` it ran on and — for a step that browsed through the account's pod from slim — its `browserPod` reconnects and fallback ([runs](runs#the-record)). `?wait=true&timeout=<s>` instead blocks until the run stops (or `timeout`, default 300, max 900) and answers the verdict the run routes give — `200` once the run has ended, however it ended: `ok: true` when it completed, `ok: false` with its `status` and `failure: { agent, reason }` when it failed or was stopped (a run that fails is the answer, not a fault in the call — it was a `500` before 29 Oct 2026); `202` still going (`timedOut`) or parked on a person (`awaitingApproval`). A start refused before any run exists — a paused account or workspace (`423`), an agent or flow that is not there (`404`), `overlap: skip` (`409`) — is answered as such and waits for nothing. Ask in short pieces: whatever sits in front of the platform cuts a request that stays silent too long (Cloudflare at 100 s, an AWS ALB at 60 s), and a flow can run for many minutes — the CLI's `--wait` asks 25 s at a time and comes back here on every `202`. DELETE erases the run's record and archived outputs (a run still going is stopped first; the ledger line stays) and needs `workspace:manage` — an admin — since 30 Oct 2026 (it was `run:start`) |
|
|
207
216
|
| `/api/workspaces/<ws>/runs/<id>/stream` | GET | server-sent events, live |
|
|
208
|
-
| `/api/workspaces/<ws>/runs/<id>/stop` | POST | destroys the sandbox, not just the record |
|
|
209
|
-
| `/api/workspaces/<ws>/runs/<id>/rerun` | POST | again — `step` to start partway, or `agent` to start at the first step that agent runs (one of the two is required). `instruction` tells that step something else this once, in place of the flow's (the flow file is not changed); the new run's `rerunOf` says `{ run, step, instruction }`. Takes `?wait=true&timeout=` like a flow start |
|
|
217
|
+
| `/api/workspaces/<ws>/runs/<id>/stop` | POST | destroys the sandbox, not just the record. `404` for no such run, `409` for one already finished |
|
|
218
|
+
| `/api/workspaces/<ws>/runs/<id>/rerun` | POST | again — `step` to start partway, or `agent` to start at the first step that agent runs (one of the two is required). `instruction` tells that step something else this once, in place of the flow's (the flow file is not changed); the new run's `rerunOf` says `{ run, step, instruction }`. Takes `?wait=true&timeout=` like a flow start. `404` for no such run, `409` for one not finished, `400` for a `step` that is not a whole number |
|
|
210
219
|
| `/api/workspaces/<ws>/runs/bulk` | POST | one action on many runs at once. `action` is `stop` or `rerun`; the runs are named by any of `runIds`, `status`, `flow`, `since`, `until`, AND-ed together, and a call naming none of them is refused rather than treated as "everything". `from` picks the step a rerun starts at, `dryRun: true` answers with what would be touched and touches nothing. At most 100 runs per call — past that it answers `422` with the count, because a filter matching more than that is almost certainly the wrong filter. Each run is its own outcome: the reply carries `matched`, `succeeded`, `failed` and a `runs` array, so one run that finished a second ago does not abort the other thirty |
|
|
211
|
-
| `/api/workspaces/<ws>/runs/<id>/approve` | POST | release a run parked on a human: `decision` (`approve` or `reject`), `note`, `reason`, `step` (one of several waiting). `payload` (a string, or JSON sent as its text, up to 20000 characters) releases a step parked on `wait: event` with that payload, as its event URL would, recorded as released by the caller — 400 with `reject` or when no such step is waiting. `run:start`. Idempotent |
|
|
220
|
+
| `/api/workspaces/<ws>/runs/<id>/approve` | POST | release a run parked on a human: `decision` (`approve` or `reject` — anything else is a 400 that decides nothing; left out only beside `payload`), `note`, `reason`, `step` (one of several waiting, its index from 0). `payload` (a string, or JSON sent as its text, up to 20000 characters) releases a step parked on `wait: event` with that payload, as its event URL would, recorded as released by the caller — 400 with `reject` or when no such step is waiting. `run:start`. Idempotent |
|
|
212
221
|
| `/api/workspaces/<ws>/runs/<id>/answer` | POST | answer a question an agent asked mid-step (`tools: [ask]`): `{question: <id>, answer}`. The agent is waiting in a live sandbox and gets it within a second or two. First answer wins — a second is `409` with the answer that stands; also `409` when the agent stopped waiting (its ask timed out) or its step is no longer running. `404` when the question is not this run's or has expired |
|
|
213
222
|
| `/api/workspaces/<ws>/runs/<id>/message` | POST | say something to a running agent: `{text, step?}` (at most 4 000 characters). It reaches the model after its next tool call, as context — it never changes the step's tools. `step` is the step's index in the run; left out, the only running step. With several running (a parallel group) and no `step`, `400` listing them in `running`, so a sibling never takes a message meant for another. `409` unless the run, and that step, are running. Replies `{ok, step, message}` |
|
|
214
223
|
| `/api/workspaces/<ws>/runs/<id>/archive` | GET | one file the run archived from an agent's `outputs/` — `agent` and `path` name it; the run page's Out column links here, and plays a recording or shows a picture inline. Served as bytes, never as a page; a `Range` header gets `206` with that slice, which is how a video seeks |
|
|
@@ -217,10 +226,10 @@ paying for the steps around it.
|
|
|
217
226
|
| `/api/workspaces/<ws>/triggers?days=` | GET | why nothing happened: one row per flow saying how often its trigger fired, how often that became a run, and what the difference was — a duplicate delivery, a throttled burst, a debounced burst still being waited out, a quarantined flow, a workspace or account paused by a person (`halted`), an `overlap: skip`, a fire missed while the platform was down. Plus every decision newest-first, and the hook/inbox delivery log, which answers the separate question of whether a request arrived and was authentic. `days` 1–365, default 7 (`since=`, its older name, still works — deprecated) |
|
|
218
227
|
| `/api/workspaces/<ws>/notify/deliveries` | GET | the outbound webhook log: every `notify:` url delivery from this workspace, newest first — `{ deliveries, total, limit, offset, endpoint }`. A delivery is `{ id, event, status, destination, attempts, attemptLog, lastStatusCode, lastError, nextAttemptAt, createdAt, updatedAt, body }`: `id` is the `X-Foldrun-Delivery` header; `status` is `pending` (a retry is due at `nextAttemptAt`), `delivered`, `failed` (gave up after six attempts) or `skipped` (the endpoint was switched off); each attempt is `{ n, at, statusCode, durationMs, response (first 500 characters), error, manual? }`. `body` is what was sent, except that a gate's `approveUrl`/`rejectUrl` (top level and in `links`) read `[redacted]` — they decide without a login, and this log is readable by every role; the receiver still gets them, on a redelivery too. `?status=`, `?event=`, `?limit=` (50, at most 200), `?offset=`. `endpoint` is `{ failingSince, lastSuccessAt, lastFailureAt, disabledAt, disabledReason }` or null. Kept 30 days |
|
|
219
228
|
| `/api/workspaces/<ws>/notify/deliveries/<id>/redeliver` | POST | send one delivery again now — the same id and body, signed afresh, to the URL `notify:` names today. `{ ok, attempt, delivery }`, always `200` when the delivery exists (whether the receiver took it is the answer); `404` when it does not. An accepted redelivery switches a disabled endpoint back on. Needs the permission that runs |
|
|
220
|
-
| `/api/workspaces/<ws>/notify/test` | POST | sends one real notification to whatever this workspace's `notify:` resolves to, and answers `{ ok, destination, detail }` — including the provider's own words when it failed, which are what name the problem. Always `200`: the request was handled, and the result is the answer
|
|
229
|
+
| `/api/workspaces/<ws>/notify/test` | POST | sends one real notification to whatever this workspace's `notify:` resolves to, and answers `{ ok, destination, detail }` — including the provider's own words when it failed, which are what name the problem. Always `200`: the request was handled, and the result is the answer — except past 10 test sends an hour for one workspace, a `429` with `Retry-After`. Needs the permission that runs, because it sends real mail |
|
|
221
230
|
| `/api/workspaces/<ws>/observe?days=` | GET | the observability report the Observe page renders — `tally` (the shared outcome counts) and `chargedUsd` beside `costUsd` on the report, each flow, day and agent (what was charged, the ledger's line or list price until settled, versus the provider's token cost); per-agent failures, retries, tokens, `cacheHitRate`, `turns` and `systemPromptChars` (each `{ n, p50, p95, max }`), per-tool calls/errors/latency and `resultSize` (characters per result, same shape), `resultChars` (their sum) and `heavyCalls` (results over 10,000 characters), per-flow duration, day series, recent failures, and `startup` — one row per start-up phase in order, `{ phase, took, at }`, each `{ n, p50, p95, max }` in seconds (`took` is the phase's own share, `at` when it ended counted from the step's start; percentiles need five samples). `days` 1–365, default 30 (`since=`, its older name, still works — deprecated) |
|
|
222
231
|
| `/api/workspaces/<ws>/history?path=&id=&limit=` | GET | every change to the workspace, newest first — `path` narrows to one file, `id` returns one revision with its before/after and a line diff, `limit` 1–500, default 100. A deploy's revision id is its commit |
|
|
223
|
-
| `/api/workspaces/<ws>/restore` | POST | put the workspace's source back as it was at a point in its history. `to`: a revision id (`r-…`), the commit a deploy named (or its prefix), an ISO date/time (the last revision at or before it) or an age (`90m`, `12h`, `3d`, `2w`) — every revision since 17 Oct 2026 holds a snapshot of the whole source. `{ to, dryRun: true }` answers `{ to: { id, sha, at, by, message }, from, added, updated, removed, files: [{ path, change, diff }], blockedBy, noop, issues, warnings }` and writes nothing; `issues` are the deploy checks that would refuse that tree, `warnings` the ones it would deploy with. The restore needs `confirm` set to the workspace's name (400 without) and takes the dry run's `expectRemoved`; it deploys that revision's snapshot as a new revision (undo: restore to `from`; `to.sha` is the same id as `to.id`, kept from when revisions were git commits), keeps runs, `state/`, storage, secrets and agent-written memory, and is refused 409 while runs are in flight or when it would remove something not in `expectRemoved`. `workspace:write
|
|
232
|
+
| `/api/workspaces/<ws>/restore` | POST | put the workspace's source back as it was at a point in its history. `to`: a revision id (`r-…`), the commit a deploy named (or its prefix), an ISO date/time (the last revision at or before it) or an age (`90m`, `12h`, `3d`, `2w`) — every revision since 17 Oct 2026 holds a snapshot of the whole source. `{ to, dryRun: true }` answers `{ to: { id, sha, at, by, message }, from, added, updated, removed, files: [{ path, change, diff }], blockedBy, noop, issues, warnings }` and writes nothing; `issues` are the deploy checks that would refuse that tree, `warnings` the ones it would deploy with. The restore needs `confirm` set to the workspace's name (400 without) and takes the dry run's `expectRemoved`; it deploys that revision's snapshot as a new revision (undo: restore to `from`; `to.sha` is the same id as `to.id`, kept from when revisions were git commits), keeps runs, `state/`, storage, secrets and agent-written memory, and is refused 409 while runs are in flight or when it would remove something not in `expectRemoved`. `workspace:write`, and `workspace:manage` when the restored `AGENTS.md` has different policy keys (`403` naming them; a dry run is not refused); audited as `workspace.restored` |
|
|
224
233
|
|
|
225
234
|
`status` is one of `queued`, `running`, `awaiting-approval`, `completed`,
|
|
226
235
|
`failed`.
|
|
@@ -280,9 +289,9 @@ one; a body that does not match the length it declared is a `400`.
|
|
|
280
289
|
|
|
281
290
|
| Route | Methods | |
|
|
282
291
|
|---|---|---|
|
|
283
|
-
| `/api/workspaces/<ws>/storage` | GET, POST, PUT, DELETE | GET lists every stored file with the quota; POST records one (`path`, `sha`, `size`); PUT `?path=` writes one; DELETE `?path=` removes one |
|
|
292
|
+
| `/api/workspaces/<ws>/storage` | GET, POST, PUT, DELETE | `404` when the workspace does not exist. GET lists every stored file with the quota; POST records one (`path`, `sha`, `size` — the record takes the length the store reports, not this; over the per-file limit or the quota the object is removed and the call refused); PUT `?path=` writes one; DELETE `?path=` removes one |
|
|
284
293
|
| `/api/workspaces/<ws>/storage/download?path=` | GET | a redirect to a presigned URL |
|
|
285
|
-
| `/api/workspaces/<ws>/storage/upload-url` | POST | a presigned PUT (`path`, `sha`) |
|
|
294
|
+
| `/api/workspaces/<ws>/storage/upload-url` | POST | a presigned PUT (`path`, `sha`, and `size` — the length in bytes; since 30 Oct 2026 the limits are checked on it and it is signed into the URL, so the bucket refuses any other length. Optional for older clients: registering the upload measures the real object against the same limits either way) |
|
|
286
295
|
| `/api/workspaces/<ws>/storage/preview?path=` | GET | the file parsed for reading, as JSON — text, a table, a document, slides, an archive listing, a mesh, a hex dump. Stored HTML and SVG come back as strings for a sandboxed frame, never served as pages. `413` over 25 MB |
|
|
287
296
|
| `/api/workspaces/<ws>/assets` | POST | create a document (`kind`, `name`, `agent`, `template`) |
|
|
288
297
|
|
|
@@ -293,10 +302,15 @@ URLs mean nothing in a run pod ever holds the bucket credential.
|
|
|
293
302
|
|
|
294
303
|
| Route | Methods | |
|
|
295
304
|
|---|---|---|
|
|
296
|
-
| `/api/workspaces/<ws>/shares` | POST, GET, DELETE | mint (`path`, `ttlDays`: days, `null` never; returns `url`, `token`, `path`, `contentType`, `expiresAt`), list, revoke (`?token=`, only a link of this workspace) |
|
|
297
|
-
| `/s/<token>` | GET, HEAD | the file itself, no credential |
|
|
305
|
+
| `/api/workspaces/<ws>/shares` | POST, GET, DELETE | mint (`path`, `ttlDays`: days, `null` never; returns `url`, `token`, `id`, `path`, `contentType`, `expiresAt`), list, revoke (`?token=` or `?id=`, only a link of this workspace) |
|
|
306
|
+
| `/s/<token>` | GET, HEAD | the file itself, no credential, streamed; HEAD reads only its length. `Cache-Control: private, no-store`, so no shared cache serves a link after it is revoked or expires. `429` past 120 a minute from one caller or 1,200 a minute for one link |
|
|
307
|
+
|
|
308
|
+
From the terminal: `foldrun storage share <path>`, `shares`, `unshare <token|id>`.
|
|
298
309
|
|
|
299
|
-
|
|
310
|
+
The list hands a link's token (and `url`) only to an admin and to the person
|
|
311
|
+
who made it — a token is the link, and it outlives the access of whoever
|
|
312
|
+
copied it. Everyone else gets the row with `masked: true`, the token cut to a
|
|
313
|
+
stub, `url: null`, and `id` (`sh_…`, a hash of the token) to revoke it by.
|
|
300
314
|
|
|
301
315
|
`POST` returns a `url` under `/s/<token>`. That URL answers without a
|
|
302
316
|
credential — the token *is* the authorisation, so it carries 24 random bytes
|
|
@@ -324,7 +338,7 @@ its header and requires a URL it can GET for itself.
|
|
|
324
338
|
|
|
325
339
|
| Route | Methods | |
|
|
326
340
|
|---|---|---|
|
|
327
|
-
| `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a workspace's own store; unsaid is the account's, which a key scoped to some workspaces may not touch. PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set` |
|
|
341
|
+
| `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a workspace's own store; unsaid is the account's, which a key scoped to some workspaces may not touch. `name` is a string (400 otherwise). The account's `RESEND_API_KEY` and `EMAIL_FROM` — the sender of everyone's sign-in mail — are set, rebound and deleted by the owner alone (403 to anyone else), here and through an OAuth connect — the owner in person: their signed-in session or the key their own `foldrun login` minted, never another key they minted. An oauth2 recipe from a caller scoped to some workspaces links to the account's saved OAuth app with the same token URL and client id but never saves or changes one (as `POST /api/oauth/clients` refuses them). PATCH also takes `workspaces` (with or instead of `sites`): `{ name, workspaces: ["sales", "ops"] }` limits an **account** secret to those workspaces — every other one finds it not set, in runs, tool tests, `notify:` (its email too), the egress proxy and MCP, for runs that start after it ([limited to some workspaces](secrets#limited-to-some-workspaces)); `null` opens it to every workspace, `[]` to none; the answer carries `workspaces` (sorted, or `null`). `ifWorkspaces` — the list you loaded, `null` for every workspace — makes it conditional: 409 when the list changed since, nothing written. PUT takes the same `workspaces` and saves it with the value in one write (the answer carries it too); it is never ignored. Account store only (400 with `workspace`), an admin over every workspace (403 for a scoped caller), names of workspaces that exist, checked under the vault's lock (400 otherwise), 404 for a secret that is not there; audited as `secret.workspaces` (PATCH) and in `secret.set` (PUT). GET of the account store lists each limited secret's `workspaces`, and `?workspace=` leaves out an account secret that workspace may not use. PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set` |
|
|
328
342
|
|
|
329
343
|
`PUT` takes `name` plus exactly one shape: `value` (a string), `file` (a PEM,
|
|
330
344
|
a cert), `oauth2`, `service_account`, `ssh`, `api`, `client_cert` (`{ cert, key, passphrase?, export? }` — mutual TLS, presented by the egress proxy to the exact sites the secret is bound to), or `identity` (`{ audience }` — keyless cloud access). They go to the vault;
|
|
@@ -341,33 +355,33 @@ Reads return which secrets exist, never their values.
|
|
|
341
355
|
| `/api/team` | GET, POST | members with their roles and workspace scope; mint an invite — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). An invite works **once**, for seven days, and a newer invite to the same address revokes the older ones still pending. Returns `id`, `path` (the invite's relative URL, shown only here), `expires`, `sent` and any `sendError` either way; the full link is in the mail. Links made before 29 Oct 2026 (`inv1`–`inv3`) are refused |
|
|
342
356
|
| `/api/team/invites?all=1` | GET | the account's invites, newest first — pending ones unless `all=1` (then accepted, revoked and expired too): `{ invites: [{ id, email, role, workspaces, invitedBy, createdAt, expiresAt, status }] }`, `email` `null` for a link anyone may use, `workspaces` `null` for all, `status` `pending` \| `accepted` \| `revoked` \| `expired`. Never the link. `team:manage` — an admin key included; a caller scoped to some workspaces sees only the invites inside its scope |
|
|
343
357
|
| `/api/team/invites/<id>` | DELETE | revoke an invite: its link stops working at once. `{ ok, revoked, invite }` — `revoked: false` when it was already revoked or expired; `404` for an id that is not this account's; `409` for one already accepted (remove the member instead). `team:manage`, a key included; a scoped caller only inside its scope, and an admin invite only by the owner. Audited as `member.invite_revoked` |
|
|
344
|
-
| `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which workspaces they may open (`workspaces`: names, or null for all); remove them. Removing someone revokes the keys and pending invites they made and any invite still pending to their address; a lower role or fewer workspaces revokes the keys and invites that reach beyond their new standing |
|
|
345
|
-
| `/api/team/transfer` | POST | hand the account to a member (`to`) — owner only
|
|
358
|
+
| `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which workspaces they may open (`workspaces`: names, or null for all); remove them. Removing someone revokes the keys and pending invites they made and any invite still pending to their address; a lower role or fewer workspaces revokes the keys and invites that reach beyond their new standing. `404` for an id that is not a member, whatever the body |
|
|
359
|
+
| `/api/team/transfer` | POST | hand the account to a member (`to`) — owner only, signed in, and re-proving it is them: `password` (the current one) and, when two-step sign-in is on, `code` (from the app, or a backup code). 400 without them, 401 when wrong, 6 tries in 15 minutes. You become an admin |
|
|
346
360
|
| `/api/usage/compute` | GET | the account's compute at every level (27 Oct 2026): `compute` is `{ vcpu, memGiB, diskGiB, stepVcpu, stepMemGiB, stepDiskGiB, source }` — the cores, GiB and GiB of disk all its running steps may hold together, the most one step may hold (each `null` for no cap), and where the pool came from (`plan`, `account` — its own `compute:` in AGENTS.md, which can only lower it — `install`, or `null`); `inUse` is `{ vcpu, memGiB, diskGiB, steps }`, what its running steps' sandboxes hold now, from their records (a step still waiting for room holds nothing; a caller scoped to some workspaces sees theirs); `workspaces` is each workspace's own `pool` (its AGENTS.md `compute:`, `null` figures for none) and `inUse`; `runs` is each live run with a pool of its own (its flow's `compute:`) or anything held, `{ workspace, runId, flow, pool, inUse }`; `waiting` lists the steps waiting for room, oldest first — `{ workspace, runId, flow, step, agent, since, why, cpus, memGiB, diskGiB, level?, runPool }`, `since` being when it first found none, its place in line, and `level` the cap that held it when it last looked. A step past any level waits, with no time limit, and starts in turn; one bigger than a level's whole cap or the step maximum fails at once ([four levels](budgets-and-billing#compute-at-four-levels), [waiting for room](budgets-and-billing#waiting-for-room)) |
|
|
347
361
|
| `/api/usage/history?days=` | GET | charged spend by flow, by agent and by workspace over time, read from the ledger rather than the run records — so it survives runs being pruned and reports what was billed rather than what was consumed. Buckets by week over three weeks, by day under. Each series carries its periods, its total, and the change between the last two COMPLETE periods, so a partial week never reads as a collapse. `unattributedUsd` is charges from before a line recorded its flow. A caller scoped to some workspaces sees only the charges in those; `days` 1–365, default 56 |
|
|
348
362
|
| `/api/account/model` | GET, PUT, DELETE | the account's own model key — what every step runs on unless an agent, workspace or the account's AGENTS.md names a `provider:`. GET: `{ set, provider, baseUrl, format, keyHint, runsOn, platformKeyAllowed }` — never the key, only its last four characters; `runsOn` is `account` (its own key), `platform` (the platform's credential, for the operator's accounts) or `none` (runs are refused until a key is set). PUT `{ provider, apiKey, baseUrl?, format? }` (needs `secrets:write`): `provider` is a preset name (anthropic, openrouter, openai, groq, … — see providers) or `custom` with an https `baseUrl` and a `format` (anthropic or openai); a Claude login token (sk-ant-oat…) is refused for any account not allowed the platform's credential. Stored as the account secrets `FOLDRUN_MODEL_PROVIDER`, `FOLDRUN_MODEL_API_KEY`, `FOLDRUN_MODEL_BASE_URL`, `FOLDRUN_MODEL_FORMAT`. DELETE removes them. Honours Idempotency-Key on PUT; audited as model.key_set / model.key_removed |
|
|
349
|
-
| `/api/account/providers` | GET, POST | GET: the model providers this account's files actually use — each one's preset name, where it is declared, the model a check would send — plus the last daily health check. POST forces one now, which spends one minimal request at each distinct endpoint, and needs the permission that runs |
|
|
350
|
-
| `/api/usage` | GET | what has been spent, by meter; each bucket's tokens are `inputTokens` (all input), `outputTokens`, `cacheReadTokens` and `cacheWriteTokens` (the part of the input the prompt cache served and stored), and `cacheHitRate` — reads over `measuredInputTokens`, the input of steps that report the split, `null` when none do. A key or member scoped to some workspaces sees those workspaces, and totals over them; `ledger` is the account's `balanceUsd` and `chargedUsd` (all time), the account
|
|
363
|
+
| `/api/account/providers` | GET, POST | GET: the model providers this account's files actually use — each one's preset name, where it is declared, the model a check would send — plus the last daily health check. POST forces one now, which spends one minimal request at each distinct endpoint, and needs the permission that runs and every workspace. A member or key scoped to some workspaces sees the account's provider blocks and its own workspaces' only, in `configured` and in the last check |
|
|
364
|
+
| `/api/usage` | GET | what has been spent, by meter; each bucket's tokens are `inputTokens` (all input), `outputTokens`, `cacheReadTokens` and `cacheWriteTokens` (the part of the input the prompt cache served and stored), and `cacheHitRate` — reads over `measuredInputTokens`, the input of steps that report the split, `null` when none do. A key or member scoped to some workspaces sees those workspaces, and totals over them; `ledger` is the account's `balanceUsd` and `chargedUsd` (all time), and `waived` the legs the account is not charged for — both `null` to a caller scoped to some workspaces, since they are the whole account's money. Since API version `2026-10-26` nothing else; earlier pins see `providerCostUsd` and `marginUsd` as `null` |
|
|
351
365
|
| `/api/approvals` | GET | every gate waiting on a person, across workspaces — one entry per waiting **step** (`workspace`, `runId`, `flow`, `step`, `agent`, `question`, `asked`, `waitingSince`), oldest first. By step status, not run status: a decided gate leaves the list at once, before the worker resumes the run. `wait: event` steps are not listed; no button answers them. Beside it, `questions`: every question an agent is asking mid-step in a running run (`kind: "question"`, `id`, `workspace`, `runId`, `flow`, `agent`, `question`, `options?`, `askedAt`) — answered with `…/runs/<id>/answer` |
|
|
352
366
|
| `/api/insights?days=&workspace=` | GET | recurring problems found in the runs of the window (see [Runs](runs#insights)): `{ days, insights: [{ id, kind, workspace, agent, tool?, title, why, fix, credits, steps, evidence: [{ workspace, runId, step }] }] }`. `kind` is `cache` (an agent's big prompt mostly uncached), `big-result` (a tool result over 20k characters sent again on every later model call), `retry-loop` (a tool erroring three or more times in a step) or `timeout` (steps using 80% or more of their `timeout:`); `credits` is about what it cost in the window, null when it is not money. `days` 1–30, 7 unasked. A key scoped to some workspaces sees theirs |
|
|
353
367
|
| `/api/issues?status=&workspace=` | GET | the account's issues: what went wrong, grouped and kept open until a person resolves it (see [Runs](runs#issues)). One issue is one desk's flow failing at one agent, or ending BLOCKED or BAD, or one platform cause across desks. Each carries `id`, `kind` (`platform`, `failed`, `blocked`, `bad`, `missed` — a scheduled fire that started no run), `status` (`open`, `acknowledged`, `snoozed`, `resolved`), `regressed` and `sinceRevision` (it was resolved and came back, since the revision its new run ran), `snoozedFor`, `workspace`/`workspaces`, `what`, `agent`, `reason`, `action` (what to do), `firstSeen`, `lastSeen`, `count`, the newest `runs`, `recoveredAt` (the flow's newest good run since — it closes nothing), `acknowledged`, `snoozedUntil`, `resolved` and the `history` of what people did. `status` is `active` unasked (open + acknowledged), or `open`, `acknowledged`, `snoozed`, `resolved`, `all`; `workspace` keeps the ones that hit it. A key scoped to some workspaces sees the issues of those |
|
|
354
368
|
| `/api/issues/<id>` | GET POST | one issue; POST acts on it: `{ action: "acknowledge" | "snooze" | "resolve" | "reopen", for?: "30m" | "4h" | "1d" | "1w", until?: ISO, times?: n, note? }` (editor or above), kept in its history with who did it, and answers `{ issue }` as it now stands. A snooze needs `for`, a future `until`, or `times` (until it happens that many more times; with a time too, whichever comes first). A platform issue is the account's: closing it needs access to every workspace. A run that goes wrong the same way after a resolve opens the issue again |
|
|
355
|
-
| `/api/account/export` | GET | the owner's copy of what the platform holds about the account, as one JSON file (`foldrun-<account>-export.json`): `workspaces` (with their flows), `members` (email, role, scope, since), `runs` (an index — id, workspace, flow, status, times, headline) and the whole `ledger` (each line's charge; the platform's provider cost
|
|
369
|
+
| `/api/account/export` | GET | the owner's copy of what the platform holds about the account, as one JSON file (`foldrun-<account>-export.json`): `workspaces` (with their flows), `members` (email, role, scope, since), `runs` (an index — id, workspace, flow, status, times, headline) and the whole `ledger` (each line's charge and what it was for; the platform's provider cost, its internal dedup `key` and `pricingVersion` are left out). `billing:manage`, so the owner; audited as `account.exported`. The markdown itself comes from `foldrun pull` or the source API |
|
|
356
370
|
| `/api/account/telemetry/test` | POST | send one made-up run as an OpenTelemetry trace to the collector `telemetry:` names — the account's, or `{ workspace }`'s — with its header secrets filled from the vault; `{ ok, status?, error?, spans?, endpoint }`. `409` when no `telemetry:` is set. Needs `workspace:manage` |
|
|
357
|
-
| `/api/account/jobs?workspace=` | GET | the four jobs (governance, guardrail, observability, evaluation) and each `AGENTS.md` field of each: `{ jobs: [{ name, title, what, fields: [{ key, account, workspace?, combine, writable }] }] }` — the account's value and the workspace's when `workspace` is given (null: unset), as written with blocks folded; `combine` is how the two meet at run time (`workspace replaces`, `either turns it on`, `both apply`, `per key`, `per field`, `level nearest, sites from both`, `account only`); `writable` is whether that scope's settings PATCH (`/api/account`, or the workspace's) writes it — the rest are written in `AGENTS.md`. See [The four jobs](four-jobs) |
|
|
371
|
+
| `/api/account/jobs?workspace=` | GET | the four jobs (governance, guardrail, observability, evaluation) and each `AGENTS.md` field of each: `{ jobs: [{ name, title, what, fields: [{ key, account, workspace?, combine, writable }] }] }` — the account's value and the workspace's when `workspace` is given (null: unset), as written with blocks folded — to a caller scoped to some workspaces the account's `notify` and `telemetry` are `{ hidden: true, … }` (set; no URL, headers or token); `combine` is how the two meet at run time (`workspace replaces`, `either turns it on`, `both apply`, `per key`, `per field`, `level nearest, sites from both`, `account only`); `writable` is whether that scope's settings PATCH (`/api/account`, or the workspace's) writes it — the rest are written in `AGENTS.md`. See [The four jobs](four-jobs) |
|
|
358
372
|
| `/api/account/pause` | GET, POST, DELETE | the account's kill switch: the same as a workspace's `/pause`, for every workspace at once. GET `{ paused, account, workspaces }` (`workspaces`: those paused on their own). POST `{ reason?, stop?: true }`, DELETE resumes the account — a workspace paused on its own stays paused. Needs `workspace:manage` and access to every workspace |
|
|
359
373
|
| `/api/account/close` | POST | the owner asks to close the account — in person, never a key, with `confirm` set to the account's name and an optional `reason`. Not a delete: the account is suspended at once (runs in flight finish, sign-in and the export still work), `closeRequested` is set on its admin state, and the platform's operator is mailed to settle the last invoice and any refund. A plan's subscription is set to stop at the end of the period already paid for — nothing renews, no refund — and `billing` says what was done (the close stands even if Stripe could not be reached; `billing` then says so). Returns `{ ok, suspended, notified, billing }`; 409 when already asked. Hosted installs only |
|
|
360
|
-
| `/api/account/backups` | GET | what is backed up for this account: `policy` (`schedule`, `keepLocal`, `keepOffsiteDays`, `encrypted`, `covers`, `excludes`), `last`, `backups` (each nightly archive that holds this account, newest first: `id`, `at`, `bytes` (the
|
|
374
|
+
| `/api/account/backups` | GET | what is backed up for this account: `policy` (`schedule`, `keepLocal`, `keepOffsiteDays`, `encrypted`, `covers`, `excludes`), `last`, `backups` (each nightly archive that holds this account, newest first: `id`, `at`, `bytes`, `files`, `runs` (always null: they measured the whole archive, which holds every account on the server, so they are not shown to one — 30 Oct 2026), `sha256` (the archive inside the encryption — what a decrypt must reproduce), `kinds` — files, database, keys — `verified`, `offsite`, `keepDays`, `encrypted` (sealed with age before it left the server; false for archives taken before October 2026), `recipient` (the key's fingerprint, `sha256:<16 hex>`, or null)), `requests` (earlier restore requests) and `workspaces` (`name`, `head`, `history`, `lastChange`) — what a restore can reach. See [Backups and restore](backups-and-restore.md) |
|
|
361
375
|
| `/api/account/backups/requests` | GET, POST | ask the platform team to restore what an account cannot restore itself. POST `{ what, target, workspace?, backupId?, note? }` (`what` is runs, state, storage or everything) records the request, mails the operator and audits it as `backup.restore_requested`; answers 201 `{ ok, request }` with `notified` saying whether the mail went. Restores nothing. `workspace:manage`, and a member scoped to some workspaces must name one. GET lists this account's requests |
|
|
362
|
-
| `/api/account/api` | GET, PATCH | how this account meets the API — GET `{ version: { current, pinned, effective, supported, supportMonths }, limits: { plan, windowSeconds, perCredential: { read, write }, perAccount: { read, write } }, usage }`. `usage` is the last 30 days — `{ days, versions: [{ version, requests, lastSeen }], deprecated: [{ route, requests, lastSeen, deprecatedAt, sunsetAt, link, callers: [{ credential, requests, lastSeen }] }] }`, `credential` naming a key by its label and prefix — or `null` when it could not be read; PATCH `{ version: "YYYY-MM-DD" \| null }` pins the version API-key requests without a `Foldrun-Version` header get (null: always current); the dashboard always gets current. `keys:manage
|
|
376
|
+
| `/api/account/api` | GET, PATCH | how this account meets the API — GET `{ version: { current, pinned, effective, supported, supportMonths }, limits: { plan, windowSeconds, perCredential: { read, write }, perAccount: { read, write } }, usage }`. `usage` is the last 30 days — `{ days, versions: [{ version, requests, lastSeen }], deprecated: [{ route, requests, lastSeen, deprecatedAt, sunsetAt, link, callers: [{ credential, requests, lastSeen }] }] }`, `credential` naming a key by its label and prefix — or `null` when it could not be read. A caller scoped to some workspaces gets `usage: null` and `usageHidden: true`: who calls which route is the whole account's; PATCH `{ version: "YYYY-MM-DD" \| null }` pins the version API-key requests without a `Foldrun-Version` header get (null: always current); the dashboard always gets current. `keys:manage`; PATCH also needs every workspace (403 to a member or key scoped to some), since the pin is every key's. See [api-usage](api-usage.md) |
|
|
363
377
|
| `/api/account/flags` | GET | the feature flags as they stand for this account — `{ flags: [{ name, description, owner, default, on, source, rollout }] }`, `source` being what decided it: `account` (an override for this account), `global` (the install-wide setting), `rollout` (a percentage of accounts, by a stable hash of account and flag; `rollout` is the percentage) or `default`. Read-only, every role; only the platform's operator changes a flag (a self-hosted install runs every flag at its default). See [Feature flags](feature-flags.md) |
|
|
364
378
|
| `/api/openapi.json` | GET | this API as an OpenAPI 3.1 document — every route and method, bearer auth, the rate-limit, version and Idempotency-Key headers, and request/response schemas for runs, flow runs, deploy, source, secrets, keys and billing. No key needed. Generated from the route files by `scripts/gen-openapi.mjs`; the dashboard renders it at Docs → API reference, `foldrun api spec` saves it |
|
|
365
|
-
| `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `compute` (`{ vcpu, memGiB, diskGiB }` — the account's own cap on what its running steps hold together, lower than the plan's; PATCH writes it as `compute: { vcpu, memory, disk }`, merged over what is set: a figure not sent is kept, `null` drops one, `compute: null` drops all), `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place |
|
|
379
|
+
| `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `compute` (`{ vcpu, memGiB, diskGiB }` — the account's own cap on what its running steps hold together, lower than the plan's; PATCH writes it as `compute: { vcpu, memory, disk }`, merged over what is set: a figure not sent is kept, `null` drops one, `compute: null` drops all), `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place. To a caller scoped to some workspaces GET says these are set, never where they go: `notify` loses its `url` and carries `hidden: true` when one is set, and `telemetry` is `{ endpoint: "", headers: {}, hidden: true }`. PATCH needs every workspace |
|
|
366
380
|
| `/api/audit?since&until&action&actor&workspace&limit&cursor&format` | GET | the account's audit log, newest first — the caller's account only, whatever a header, query or body names. The owner and unscoped admins (people, or `admin` keys); `audit:read`, and refused to a member or key scoped to some workspaces, because the log is the whole account's. `since`/`until`: `7d`, `24h`, `30m` or a date; `action`: exact (`apikey.created`) or a family (`apikey`); `actor`: exact (an email, `key:<label>`, `support:<email>`); `workspace`: entries about one; `limit` 1–1000 (100; 1000 for CSV); `cursor`: the `next` of the page before. JSON `{ entries: [{ id, at, actor, action, subject, detail }], next, retention }`; `format=csv` downloads the same rows (`x-next-cursor` header when there are more). Records sign-ins and refusals, sign-outs, session revokes, password and email changes, MFA on/off, key mint/rotate/revoke, invites, joins, role/scope changes, removals, ownership transfers, secrets set/deleted (by name — never a value), deploys, workspace deletes, plan and billing changes, export and close requests, and `support.viewed`/`support.ended`. The platform operator's own levers (`operator.*`) are the platform's record and not listed. Kept for the life of the account |
|
|
367
|
-
| `/api/avatars/<kind>/<id>` | GET, PUT, DELETE | a picture for a `user` (their own id), a `workspace` (its name) or the `account` (the tenant). PUT the bytes of a PNG, JPEG or WebP under 1 MB; a person sets their own, an admin a workspace's or the account's. GET needs a signed-in tenant and is privately cached for a year — the URL's `?v=` changes with the picture |
|
|
381
|
+
| `/api/avatars/<kind>/<id>` | GET, PUT, DELETE | a picture for a `user` (their own id), a `workspace` (its name) or the `account` (the tenant). PUT the bytes of a PNG, JPEG or WebP under 1 MB; a person sets their own, an admin a workspace's or the account's. GET needs a signed-in tenant — a workspace's picture, a caller who may open that workspace (403 otherwise) — and is privately cached for a year — the URL's `?v=` changes with the picture |
|
|
368
382
|
| `/api/search?q=` | GET | find anything in the account by name — workspaces, agents, flows, tools, skills, knowledge, memory, runs (by id, flow or headline); ranked, at most six per kind. The dashboard's Find palette reads it |
|
|
369
|
-
| `/api/schedule` | GET, POST | GET: every scheduled flow with `valid` (the cron parses) and `upcoming` (the next three fires). POST: tick the scheduler now —
|
|
370
|
-
| `/api/library/<kind>?path=` | GET, POST, PUT, DELETE | account-level shared documents (`name`, `content`, `path`, `template`) |
|
|
383
|
+
| `/api/schedule` | GET, POST | GET: every scheduled flow with `valid` (the cron parses) and `upcoming` (the next three fires). POST: tick the scheduler now for this account alone — its due cron, `once:` and watch flows go now (they were due anyway); `workspace:manage` over every workspace; returns `{ ok, fired }`. An impossible cron (`0 0 30 2 *`) is `valid` with `upcoming: []` |
|
|
384
|
+
| `/api/library/<kind>?path=` | GET, POST, PUT, DELETE | account-level shared documents (`name`, `content`, `path`, `template`); DELETE `{ path }` removes one file or folder — `.` (the whole shelf) is refused |
|
|
371
385
|
| `/api/library/gallery` | GET, POST | GET: every tool the platform ships to every account, whole (`tools: [{ name, kind, title, description, files: [{ kind, file, content }], installed }]`, `installed` being `current`, `differs` or null for this account's own copy) — what `foldrun gallery` reads and lays down on a laptop. POST: update an installed gallery tool to the version the platform ships (`tool`) — written through the revision log, so the previous copy is one revision back |
|
|
372
386
|
|
|
373
387
|
## Roles
|
|
@@ -378,7 +392,7 @@ least role that may take that action. Reads are open to every role.
|
|
|
378
392
|
| role | may |
|
|
379
393
|
|---|---|
|
|
380
394
|
| `viewer` | read everything — workspaces, runs and their output, files, history, usage |
|
|
381
|
-
| `editor` | + edit files, upload, deploy, push; run, stop, re-run, approve and promote runs; test tools |
|
|
395
|
+
| `editor` | + edit files, upload, deploy (to a workspace that exists), push; run, stop, re-run, approve and promote runs; test tools |
|
|
382
396
|
| `admin` | + create and delete workspaces; write secrets and connect credentials; mint keys; invite, re-role and remove editors and viewers |
|
|
383
397
|
| `owner` | + billing; make and unmake admins; transfer the account |
|
|
384
398
|
|
|
@@ -397,11 +411,11 @@ person: a key names an account, never a who.
|
|
|
397
411
|
|
|
398
412
|
| Route | Methods | |
|
|
399
413
|
|---|---|---|
|
|
400
|
-
| `/api/billing` | GET, POST | balance and recent ledger entries; POST answers `404` to every caller — credit comes through checkout (`/api/billing/checkout`) or an adjustment by the platform's operator |
|
|
414
|
+
| `/api/billing` | GET, POST | balance and recent ledger entries — to a member or key scoped to some workspaces, only those workspaces' charges (no other workspace's runs, no top-ups or refunds); POST answers `404` to every caller — credit comes through checkout (`/api/billing/checkout`) or an adjustment by the platform's operator |
|
|
401
415
|
| `/api/billing/checkout` | POST | a Stripe session (`usd`) |
|
|
402
416
|
| `/api/billing/confirm?session_id=` | GET | settle one |
|
|
403
417
|
| `/api/billing/card` | POST | save a card |
|
|
404
|
-
| `/api/billing/details` | GET, PUT | who the invoices are made out to — GET `{ details, stripe, customer, tax }` for anyone who can see billing; PUT (the owner) `legalName` (required), `email`, `abn` (checked against the ABN rule), `address` `{ line1, line2, city, state, postcode, country }` (two-letter country) or `null`. Every problem comes back at once as `errors` with a `400`. Kept first, then sent to the Stripe customer (name, address, the ABN as its `au_abn` tax id): answers `synced`, and `syncError` with Stripe's words when Stripe refused — the details stand either way |
|
|
418
|
+
| `/api/billing/details` | GET, PUT | who the invoices are made out to — GET `{ details, stripe, customer, tax }` for anyone who can see billing and every workspace (403 to a member or key scoped to some, as for the statement); PUT (the owner) `legalName` (required), `email`, `abn` (checked against the ABN rule), `address` `{ line1, line2, city, state, postcode, country }` (two-letter country) or `null`. Every problem comes back at once as `errors` with a `400`. Kept first, then sent to the Stripe customer (name, address, the ABN as its `au_abn` tax id): answers `synced`, and `syncError` with Stripe's words when Stripe refused — the details stand either way |
|
|
405
419
|
| `/api/billing/portal` | POST | a Stripe Billing Portal session for the account's customer (the owner): answers `url`. Optional `returnTo`, a `/dashboard/…` path to come back to. `501` without Stripe |
|
|
406
420
|
| `/api/billing/statement?month=&format=` | GET | one month of the ledger as a statement. JSON by default; `format=csv` downloads it with the month, the account and the spent and added totals in its header. `month` is `YYYY-MM`, default the current month. What the customer sees is the charge; the platform's provider cost is not on it. The whole account's money, so refused (403) to a member or key scoped to some workspaces, as the audit log is |
|
|
407
421
|
| `/api/billing/wallet` | GET, PUT | the balance summary (burn, runway, daily spend, month to date, the suggested top-up), the refill rule and the low-balance email — GET `{ enabled, stripe, summary, cardSaved, autoTopUp, email, dunning }`, PUT `autoTopUp`, `email`. `dunning.status` is `none`, `grace` (a plan invoice failed; runs go on until `graceUntil`) or `suspended` (new runs paused until it is paid), with `payUrl`, `amountDue` (minor units) and `currency` |
|
|
@@ -432,20 +446,20 @@ X-Foldrun-Cli: 0.6.0 # the CLI released with this version (absent
|
|
|
432
446
|
| Route | Methods | |
|
|
433
447
|
|---|---|---|
|
|
434
448
|
| `/api/auth/signup` | POST | `email`, `password`, `account`, `invite`, `setup`. An install with `FOLDRUN_SETUP_TOKEN` set creates its first account only with `setup` equal to it (403 otherwise); once an account exists the token does nothing. Rate limited per address and per caller. With signups closed every address gets the same refusal, so the form cannot be used to discover which addresses are registered |
|
|
435
|
-
| `/api/auth/login` | POST | `email`, `password` |
|
|
449
|
+
| `/api/auth/login` | POST | `email`, `password`. Wrong passwords are limited per account: 8 a quarter hour from one caller when a trusted proxy names the caller (`FOLDRUN_TRUST_PROXY`), so a stranger failing as someone locks out only themselves, and 40 from every caller together, reaching which mails the person; with no caller address, 8 per account from anyone. A 429 carries `Retry-After` |
|
|
436
450
|
| `/api/auth/logout` | POST | ends the session |
|
|
437
451
|
| `/api/auth/session` | GET | who am I |
|
|
438
452
|
| `/api/auth/sessions` | GET, DELETE | list; revoke one (`id`) or the rest (`others`) |
|
|
439
453
|
| `/api/auth/password` | POST | `current`, `next` — at least 10 characters, not your email, not in a known breach |
|
|
440
|
-
| `/api/auth/email` | POST | `email`, `password` — move your login to a new address
|
|
454
|
+
| `/api/auth/email` | POST | `email`, `password` — ask to move your login to a new address. Nothing moves yet: that address is mailed a link, and clicking it makes the move, verifies the address, ends your other sessions and tells the old address. The answer (`pending: true`) is the same whether or not the address already has a login — if it does, the mail there says so instead. 5 a day. An install that can send no mail (no platform mail key and no account `RESEND_API_KEY`/`EMAIL_FROM`) refuses with 409 `{ error, code: "mail_not_configured" }` saying how to set mail up — the login stays where it is |
|
|
441
455
|
| `/api/auth/name` | POST | `firstName`, `lastName` — optional halves, null clears one; shown by email when empty |
|
|
442
|
-
| `/api/auth/forgot` | POST | `email`. Always 200 with the same sentence, whatever the address; a reset link goes to the inbox if there is an account. 3 per address per hour |
|
|
456
|
+
| `/api/auth/forgot` | POST | `email`. Always 200 with the same sentence, whatever the address; a reset link goes to the inbox if there is an account. 3 per address per hour (a 429, the same for any address), 20 per caller per hour when a trusted proxy names the caller; and on the mail itself, a ceiling for the install per hour of which one caller may spend at most 10 — past either, the answer is the same sentence and no mail goes |
|
|
443
457
|
| `/api/auth/reset` | POST | `token` (from the link), `password`. Works once and for 30 minutes; every other session of yours ends; signs you in |
|
|
444
|
-
| `/api/auth/verify?token=` | GET | the link in the confirmation email — marks the address verified and lands on the dashboard |
|
|
458
|
+
| `/api/auth/verify?token=` | GET | the link in the confirmation email — marks the address verified and lands on the dashboard. The link an email change mails moves the login here too, once, and not after a password change |
|
|
445
459
|
| `/api/auth/verify/resend` | POST | send the confirmation again, to the signed-in person, 3 an hour |
|
|
446
460
|
| `/api/auth/mfa/setup` | POST | start enrolling a second factor: `secret`, `uri`, a `qr` data URL, and an `enrol` token — nothing is stored yet |
|
|
447
|
-
| `/api/auth/mfa/enable` | POST | `enrol`, `code` from the app. Stores the secret (sealed) and returns eight `backup` codes exactly once |
|
|
448
|
-
| `/api/auth/mfa/verify` | POST | the second step of a sign-in: `challenge` (from `/api/auth/login` when it answered `mfa: true`) and `code` — six digits or a backup code. 6 tries per five minutes |
|
|
461
|
+
| `/api/auth/mfa/enable` | POST | `enrol`, `code` from the app. Stores the secret (sealed) and returns eight `backup` codes exactly once, and ends the person's other sessions as a password change does (`otherSessionsEnded`; this browser stays signed in) |
|
|
462
|
+
| `/api/auth/mfa/verify` | POST | the second step of a sign-in: `challenge` (from `/api/auth/login` when it answered `mfa: true`) and `code` — six digits or a backup code. 6 tries per five minutes; after 10 wrong six-digit codes in a row they are paused for up to a day (a backup code still works) and the person is mailed. A 429 carries `Retry-After` |
|
|
449
463
|
| `/api/auth/mfa/disable` | POST | `password` and `code` — a session alone is not enough to remove the second factor |
|
|
450
464
|
| `/api/auth/timezone` | POST | `timezone` — what a cron expression means |
|
|
451
465
|
|
|
@@ -463,9 +477,9 @@ signed-in person, never by a key — mints an ordinary API key at their role.
|
|
|
463
477
|
|---|---|---|
|
|
464
478
|
| `/api/cli/login` | POST | `hostname` → `{ id, code, verifyUrl, expiresAt, interval }`. Open: there is no credential yet. Ten-minute lifetime |
|
|
465
479
|
| `/api/cli/login/<id>` | GET | `{ status }` — `pending`, `denied`, `expired`, or `approved` with `token`, `account`, `email`, `role`. The key is returned once; the request is gone after |
|
|
466
|
-
| `/api/cli/authorize` | GET, POST | `?code=` describes the request
|
|
480
|
+
| `/api/cli/authorize` | GET, POST | `?code=` describes the request: machine, expiry, `createdAt`, `requestedFrom` (the asking network as an IPv4 /24 or IPv6 /48, from the trusted proxy — null when not known), `requestedCountry` (behind Cloudflare; else null), `sameNetwork` (whether the browser looking is on that network; null when either is not known) and `approveBy`. POST `{ code, decision }` from a session approves (mints the key, labelled `cli · <hostname>`, ending in 90 days — the CLI renews it itself before then, see `/api/keys/<id>/rotate`) or denies — `decision` is `approve` or `deny`, and absent approves; any other word is a `400`. A request more than five minutes old can no longer be approved (`410`; it can still be denied) — device-code phishing, RFC 8628 §5.4. Every role may sign its own CLI in; an owner's key is an admin's |
|
|
467
481
|
| `/api/me` | GET | who is calling: `account`, `owner`, `role`, `workspaces` (null: all), and the `actor` — a person's email, or a key's id, label, prefix, who minted it, `expiresAt` (null: never) and `origin` (`cli-login` for a key `foldrun login` minted, else null) |
|
|
468
|
-
| `/api/me/onboarding` | GET, PATCH | the account's getting-started steps, each derived from what is really there — `{ steps: [{ id, title, why, href, cli?, done }], done, total, complete, next, dismissed, dismissedAt }`. Steps: `model` (first; only for an account that must bring its own key — done once it has one, or a `provider:` block in the account's AGENTS.md), `workspace`, `agent` (an agent written or deployed after the workspace was made), `run`, `success` (a completed run), `secret`, `trigger` (a schedule or webhook), `teammate` (a second member), `billing` (hosted, not fully waived: a saved card or a plan), `cli` (any API key or CLI login). PATCH `{ dismissed: true or false }` hides or brings back the dashboard card for the signed-in person (kept in their prefs); a key reads `dismissed: false` and cannot PATCH |
|
|
482
|
+
| `/api/me/onboarding` | GET, PATCH | the account's getting-started steps, each derived from what is really there — `{ steps: [{ id, title, why, href, cli?, done }], done, total, complete, next, dismissed, dismissedAt }`. Steps: `model` (first; only for an account that must bring its own key — done once it has one, or a `provider:` block in the account's AGENTS.md), `workspace`, `agent` (an agent written or deployed after the workspace was made), `run`, `success` (a completed run), `secret`, `trigger` (a schedule or webhook), `teammate` (a second member), `billing` (hosted, not fully waived: a saved card or a plan), `cli` (any API key or CLI login). A caller scoped to some workspaces is answered over those workspaces alone — no other workspace's name is in a step's `href`. PATCH `{ dismissed: true or false }` hides or brings back the dashboard card for the signed-in person (kept in their prefs); a key reads `dismissed: false` and cannot PATCH |
|
|
469
483
|
| `/api/me/inbox` | GET, POST | your inbox — what waits on you across the workspaces you may see. GET `{ person, items: [{ id, kind (approval, question, issue, proposal, run), bucket (mine, started, team), why, workspace, title, detail, at, href, read, dismissed }], counts: { mine, started, team, unread } }`, newest first. `mine` is assigned to you (named in `approvers:`, owner of the flow or agent, or you asked for the proposal); `started` is runs you started — failed or BLOCKED/BAD this week, a gate on one (someone else decides it), a question it asked; `team` is the rest that waits in your workspaces. By default `mine` and `started`; `?bucket=mine\|started\|team\|all`, `?kind=`, `?workspace=`, `?dismissed=1` for what you set aside. `counts.unread` is unread `mine` + `started`. POST `{ ids \| id, action: read\|unread\|dismiss\|restore }` changes your view only — dismissing never decides a gate or resolves an issue; ids name an occurrence, so a thing that happens again is new. A key acts for the person who minted it, inside the key's own scope; one no person minted is a `400` |
|
|
470
484
|
| `/api/me/notifications` | GET, PATCH | what mail you get. GET `{ email, categories: [{ category, label, description, required, why?, perWorkspace, enabled, workspaces: { <ws>: bool } }] }` for `security`, `invites`, `billing`, `account` (required — always sent) and `run-alerts`, `approvals` (per workspace), `low-balance`, `product-updates`. PATCH `{ category, enabled, workspace? }` or `{ preferences: [ … ] }`; answers the same as GET. Turning a required category off is a `409` with the reason; `workspace` on an account-wide category is a `400`; `enabled: true` account-wide clears that category's per-workspace offs. A key acts for the person who minted it |
|
|
471
485
|
| `/api/me/preferences` | GET, PATCH | your own display preferences: `{ theme, runViews }` — `theme` is `system` (the default: follow the computer's light or dark setting), `light` or `dark`; `runViews` your saved run searches, `[{ name, query }]` (see [Runs](runs#searching-runs)). PATCH `{ theme }` and/or `{ runViews }` (the whole list, at most 20, each query of the runs filters) answers the same; anything else is a `400`. Kept in your prefs, so it follows you to every browser; the dashboard applies it on the server, before the first paint. A key acts for the person who minted it; a key minted by nobody is a `400` |
|
|
@@ -476,20 +490,20 @@ signed-in person, never by a key — mints an ordinary API key at their role.
|
|
|
476
490
|
| Route | Methods | |
|
|
477
491
|
|---|---|---|
|
|
478
492
|
| `/api/oauth/clients` | GET, POST, DELETE | saved OAuth apps (`name`, `client`, `config`). `config`: `authorize_url`, `token_url`, `client_id`, `client_secret` (empty for a public app), `scopes`, optional `authorize_extra` (`{ name: value }` added to the authorize URL — the flow's own parameters are refused), `pkce` (false to turn it off), `issuer` |
|
|
479
|
-
| `/api/oauth/start` | POST | begin a connection (`client`, `secret`, `workspace`, optional `scopes`). From a signed-in browser: `{ url }` is the provider's consent, bound to that browser by a cookie the callback checks, with PKCE. With an API key: `{ url, handoff: true }` is a dashboard page where a signed-in person accepts first (`foldrun connect --client` opens it). `scopes` (space-separated, as the provider spells them) is what this connection asks for instead of the client's default, and the connection keeps it for its reconnects — one saved app serves any number of connections at different scopes |
|
|
493
|
+
| `/api/oauth/start` | POST | begin a connection (`client`, `secret`, `workspace`, optional `scopes`). `secret` is checked as `PUT /api/secrets` checks a name — the account's `RESEND_API_KEY`/`EMAIL_FROM` are the owner's alone (403), and so is accepting a hand-off for them. From a signed-in browser: `{ url }` is the provider's consent, bound to that browser by a cookie the callback checks, with PKCE. With an API key: `{ url, handoff: true }` is a dashboard page where a signed-in person accepts first (`foldrun connect --client` opens it). `scopes` (space-separated, as the provider spells them) is what this connection asks for instead of the client's default, and the connection keeps it for its reconnects — one saved app serves any number of connections at different scopes |
|
|
480
494
|
| `/api/oauth/callback` | GET | where the provider returns — refuses a consent that comes back to another browser, and an `iss` that is not the app's issuer |
|
|
481
495
|
| `/api/identity?workspace=` | GET | keyless cloud identity: `{ enabled, issuer, subject, tokenSeconds }` — the issuer a cloud must trust and the subject pattern each agent's tokens carry (`account:<a>:workspace:<w>:agent:<agent>`). Open (no key), outside `/api`: `/.well-known/openid-configuration` and `/.well-known/jwks.json`, 404 when the install does not issue tokens |
|
|
482
496
|
| `/api/oauth/handoff/<id>` | POST | accept a connection started from a terminal: a signed-in person only, never a key; answers `{ url }`, the provider's consent bound to this browser. Used once, ten minutes |
|
|
483
|
-
| `/api/oauth/reconnect` | POST | reconnect a secret with the client it was connected with — no client id (`secret`, `workspace`, `provider`, optional `scopes`) → `{ url }`; it asks for `scopes` when given, else the scopes the secret was connected with, else the client's default |
|
|
497
|
+
| `/api/oauth/reconnect` | POST | reconnect a secret with the client it was connected with — no client id (`secret`, `workspace`, `provider`, optional `scopes`) → `{ url }`; `secret` is checked as `PUT /api/secrets` checks a name; it asks for `scopes` when given, else the scopes the secret was connected with, else the client's default |
|
|
484
498
|
| `/api/oauth/connections` | GET | each oauth2 secret's grant: saved client, `status` (ok, expiring, expired, failed, no-client), days left, last error |
|
|
485
499
|
|
|
486
500
|
## Triggers
|
|
487
501
|
|
|
488
502
|
| Route | Methods | |
|
|
489
503
|
|---|---|---|
|
|
490
|
-
| `/api/hooks/<tenant>/<ws>/<flow>` | POST | run a flow from outside. The token may be sent as `Authorization: Bearer <token>`, as `X-Foldrun-Token`, or as `?token=` in the URL — in that order of preference, because a URL leaks into proxy logs, access logs and browser history while a header does not; the query string stays supported because most webhook senders have nowhere to put a header. The token is derived, not stored. A flow with `signature:` (github, stripe, slack, hmac) and `signing_secret:` also has the provider's HMAC checked — a Slack `url_verification` body is answered with its challenge and starts nothing; refused deliveries are logged as `invalid-signature` |
|
|
504
|
+
| `/api/hooks/<tenant>/<ws>/<flow>` | POST | run a flow from outside. The token may be sent as `Authorization: Bearer <token>`, as `X-Foldrun-Token`, or as `?token=` in the URL — in that order of preference, because a URL leaks into proxy logs, access logs and browser history while a header does not; the query string stays supported because most webhook senders have nowhere to put a header. The token is derived, not stored. A flow with `signature:` (github, stripe, slack, hmac) and `signing_secret:` also has the provider's HMAC checked — a Slack `url_verification` body is answered with its challenge and starts nothing; refused deliveries are logged as `invalid-signature`. The signature, `idempotency: body:` and `filter:` read the whole body; the run is handed its first 20,000 characters. Wrong tokens from one caller are limited (30 a minute, then `429`) where the install knows the caller's address (`FOLDRUN_TRUST_PROXY`), as for an inbox and an event URL |
|
|
491
505
|
| `/api/inbox/<tenant>/<ws>/<flow>` | POST | the token as for a hook (`Authorization: Bearer`, `X-Foldrun-Token`, or `?token=`). An inbound email for a `trigger: email` flow — JSON (`from`, `to`, `subject`, `text` or `html`; Resend's `data` wrapper understood) or an inbound-parse form (Mailgun, SendGrid). Same token as the hook |
|
|
492
|
-
| `/api/events/<tenant>/<ws>/<id>?token=` | POST | release a run parked on `wait: event`; the body becomes the step's event payload. The
|
|
506
|
+
| `/api/events/<tenant>/<ws>/<id>?token=` | POST | release a run parked on `wait: event`; the body becomes the step's event payload. The URL is printed in the waiting step's trace and carries `&step=<index>`: its token is that step's, for that one park, so it releases that step only and a later `wait: event` of the same run gets its own URL. `409` once that gate is no longer waiting (released already, or parked again under a new URL). URLs printed before 30 Oct 2026 (no `step=`) still release a step parked under them. Wrong tokens are a `401`, limited per caller as a hook's are |
|
|
493
507
|
| `/api/approve/<tenant>/<ws>/<id>?token=` | GET, POST | decide a run parked on a human, from the link in its notification. GET shows what is waiting and two buttons — it never decides, because inbox link-checkers follow GETs. POST `decision` (`approve` or `reject`) and an optional `note`, form-encoded or JSON; answers JSON when `Accept` prefers it. The token is derived from the run id under the install key, not stored, so a key rotation kills every link. Needs `FOLDRUN_PUBLIC_URL` to be minted at all |
|
|
494
508
|
| `/api/workspaces/<ws>/hooks/<flow>` | GET | read the flow's webhook URL without changing it: `{ ok, flow, path, url }` — `path` carries the token, `url` is it made absolute with `FOLDRUN_PUBLIC_URL` (null when that is unset). `workspace:manage`, as rotate and the settings page that shows it, since the URL is a credential. `404` for no such flow, `409` for a flow that is not `trigger: webhook` |
|
|
495
|
-
| `/api/workspaces/<ws>/hooks/<flow>/rotate` | POST | new token, old URLs stop working |
|
|
509
|
+
| `/api/workspaces/<ws>/hooks/<flow>/rotate` | POST | new token, old URLs stop working. `404` for no such flow, `409` for a flow that is not `trigger: webhook`, as GET `…/hooks/<flow>` answers |
|
package/docs/checks.md
CHANGED
|
@@ -95,7 +95,10 @@ and the tool text of MCP servers reached by URL
|
|
|
95
95
|
([`content/mcp-tool-text`](#contentmcp-tool-text)).
|
|
96
96
|
|
|
97
97
|
- **When you ask:** Checks → **Online checks**, `foldrun check --to <ws>
|
|
98
|
-
--online`, or `GET /api/workspaces/<ws>/check?online=1
|
|
98
|
+
--online`, or `GET /api/workspaces/<ws>/check?online=1` — editor and
|
|
99
|
+
above, since it sends the platform out to OSV and your MCP servers. The
|
|
100
|
+
answer is kept for 10 minutes while the files are unchanged, and a
|
|
101
|
+
workspace gets six fresh online passes per 10 minutes.
|
|
99
102
|
- **Every day by itself:** the platform rescans every workspace, offline and
|
|
100
103
|
online. The first rescan of each source records what is there. After
|
|
101
104
|
that, a security finding that was not there before goes to the
|
|
@@ -206,6 +209,20 @@ key**: it has already been copied, into git history if nowhere else.
|
|
|
206
209
|
References (`${NAME}`, `$NAME`, `process.env.X`), names, and obvious samples
|
|
207
210
|
(`your-key-here`, `xxxx`, AWS's `…EXAMPLE`) are not findings.
|
|
208
211
|
|
|
212
|
+
### secret/signing-secret-value
|
|
213
|
+
|
|
214
|
+
*warn · ASI03.* A flow's `signing_secret:` or `notify: signing_secret:` holds
|
|
215
|
+
something that is not a secret's name. Both name a vault entry —
|
|
216
|
+
`signing_secret: GITHUB_WEBHOOK_SECRET` or `${GITHUB_WEBHOOK_SECRET}` — and
|
|
217
|
+
are looked up by that name. A value written there is never found, so every
|
|
218
|
+
signed delivery to the flow is refused and every notification goes out
|
|
219
|
+
unsigned, and the value itself is deployed and versioned in plain text.
|
|
220
|
+
|
|
221
|
+
Put it in the vault (`foldrun secrets set NAME`), write the name, and rotate
|
|
222
|
+
it. The finding never repeats the value, and neither does any answer that
|
|
223
|
+
shows the setting (notify's test send names the secret, or says it is not a
|
|
224
|
+
name).
|
|
225
|
+
|
|
209
226
|
### content/hidden-unicode
|
|
210
227
|
|
|
211
228
|
*warn · ASI01, ASI04, ASI06.* Zero-width characters, bidirectional overrides
|
|
@@ -361,6 +378,15 @@ place in `@foldrun/core` (`frontmatter-fields.ts`). The editor's completions
|
|
|
361
378
|
come from the same list, so what the editor suggests and what `check`
|
|
362
379
|
accepts cannot drift apart.
|
|
363
380
|
|
|
381
|
+
### config/cron-never-fires
|
|
382
|
+
|
|
383
|
+
*warn.* A `schedule:` the scheduler can read but whose day never comes:
|
|
384
|
+
`0 0 30 2 *` — every field is in range, and no February has a 30th. The flow
|
|
385
|
+
never runs and the schedule page lists no next run for it. Checked with the
|
|
386
|
+
scheduler's own rule (`cronCanFire` in `@foldrun/core`), so `check` and the
|
|
387
|
+
scheduler always agree. A day every named month has, or a weekday beside the
|
|
388
|
+
day (either then matches), fixes it.
|
|
389
|
+
|
|
364
390
|
### config/conflict
|
|
365
391
|
|
|
366
392
|
*error.* A field written twice: at the top of the frontmatter and inside its
|
package/docs/cli.md
CHANGED
|
@@ -42,7 +42,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
42
42
|
| `foldrun check [dir]` | validate agents, flows, tools, evals, knowledge — offline. At an account root: every workspace, then the shared library. Includes each agent's colleagues: an `agents:` or `subagents:` name that is not an agent, a sub-agent with no `description:`, a sub-agent that would hold none of its tools inside its parent's. Signed in, it also asks the platform's open `/api/version` which Chrome its runner image has, and warns when a pinned `web.browse.user_agent:` claims another major ([why](tools#how-this-agents-browser-presents-itself)); it warns about the old `web.browse.session:` key too (now `vendor_session:`). Hooks: a `hooks/<name>/` folder that is not a valid hook (`on:`, `run.mjs` beside `hook.md`, `tool:` only on tool events, `timeout:` 1 to 120), and a `hooks:` name in an agent or an AGENTS.md that is in neither `hooks/` nor the library, are errors; a `tool.call` hook on an agent whose `web.search:` (or `web.fetch:`) the model provider runs on its own servers is a warning — those calls never reach the hook. It is also the security scanner: a credential written into any file, invisible Unicode, override phrases in knowledge and skills, an agent that reads the web while holding a secret and an open way out, `curl \| sh`, an MCP server at no fixed version, a typo of a frontmatter field. Every finding names its rule (`secret/hardcoded`, `agent/config`, …); see [Checks](checks) |
|
|
43
43
|
| `foldrun check --security` | only the security rules (secret, security, content, supply-chain), exiting 1 on a warning. Also `--rule <id or category>` (repeatable), `--fail-on error\|warn\|info\|never`, `--format text\|json\|sarif` (`--json`; `--out <file>`), `--changed` (only files changed against git HEAD; `--base <ref>`), `--write-baseline` (accept today's findings into `.foldrun/check-baseline.json`; `--no-baseline`), `--rules` (list every rule). A `foldrun-ignore <rule>: <reason>` comment on the line before a finding silences it; the reason is required. [Checks](checks) |
|
|
44
44
|
| `foldrun extract [dir]` | move each single-file script tool — a `tools/<name>.md` with its program in a fenced block — into a folder: `tools/<name>/tool.md` with `run:` pointing at `run.js`, `run.py` or `run.sh` beside it. Frontmatter is edited as text, never re-serialised, so the diff is only what moved. A tool that already has a folder is left for you; `--dry-run` lists what it would do |
|
|
45
|
-
| `foldrun check --to <ws>` | validate the copy that is DEPLOYED, rather than the folder in front of you — a workspace edited through the API, by an agent or by `foldrun source put`, has had no way to be checked short of spending a run. The files are fetched into a temporary folder and the ordinary check runs over them, so there is one copy of the rules; the output names the workspace and the platform it checked. `--online` adds the network checks the platform runs: known vulnerabilities for exact runtime pins and remote MCP servers' tool text, and what could not be checked |
|
|
45
|
+
| `foldrun check --to <ws>` | validate the copy that is DEPLOYED, rather than the folder in front of you — a workspace edited through the API, by an agent or by `foldrun source put`, has had no way to be checked short of spending a run. The files are fetched into a temporary folder and the ordinary check runs over them, so there is one copy of the rules; the output names the workspace and the platform it checked. `--online` adds the network checks the platform runs: known vulnerabilities for exact runtime pins and remote MCP servers' tool text, and what could not be checked (an editor's key or above; the platform keeps the answer 10 minutes while the files are unchanged) |
|
|
46
46
|
| `foldrun agent run <name>` | run one agent once on a platform, with no flow file: a flow of one step. `--task "…"` is the instruction and is required. Prints the run id and how to follow it; `--wait` holds on (in 25-second pieces, as `invoke` does) and then prints the same report `foldrun report` would; `--test` makes it a [test run](runs#test-runs) |
|
|
47
47
|
| `foldrun agent link <agent>` | add to an agent's team, in its own frontmatter — `--subagent <worker>` (`subagents:`, a worker it delegates to), `--consult <agent>` (`agents:`, a colleague it asks) or `--can-ask` (`ask` in `tools:`, so it may ask you mid-step). The edit is core's, the one the canvas's docks make: only the lines of that one list change, flow style stays flow style, comments and the prose stay byte for byte. A sub-agent without a `description:` needs one, because the model picks a sub-agent by it — asked for at a terminal, `--description "…"` otherwise, and written into the worker's file first. `--isolated` also writes `sandbox: own` on the worker: each job it is handed runs in its own sandbox, with its own tools, secrets and network, not cut to the delegating agent's; its reply comes back with the files it wrote (`foldrun docs agents`). Says which flows use the agent ("used by 3 flows"), since the change reaches all of them. Prints the diff, and refuses an edit `foldrun check` would call an error; `--dry-run` writes nothing. In this folder by default (`--workspace <name>` in an account with several); `--to <workspace>` edits the deployed copy through `PATCH /api/workspaces/<ws>/agents/<name>`. In this folder it re-reads each file just before writing — after the description prompt, after `check` — and refuses, writing nothing to either file, when one changed since it was read |
|
|
48
48
|
| `foldrun agent import <workspace>/<agent>` | copy an agent you already have in another workspace into this one: its `agent.md` and own `skills/`, `scripts/`, `knowledge/` — never `memory/`, `outputs/` or `state/`. Into the workspace you stand in, or `--workspace <name>`; `--as <name>` imports it under another name (and rewrites `name:`), which a name clash requires. `--to <workspace>` does it on the platform (`POST /api/workspaces/<ws>/agents/import`) and lists the tools, skills, scripts and secrets the copy uses that the workspace lacks. See [Importing an agent](workspaces#importing-an-agent-you-already-have) |
|
|
@@ -85,7 +85,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
85
85
|
| `foldrun logs [run-id]` | recent runs in one workspace, or one run's whole event trail. `--local` reads this machine's store even when signed in; `foldrun runs --local` is the same command and prints the same thing |
|
|
86
86
|
| `foldrun runs` | what has run lately across the whole account: when, workspace, flow, status, steps done, how long, the credits it was charged (its token cost in dollars until the ledger settles it) and the run's own one-line summary. A completed run shows its verdict beside the status — `GOOD`, `BAD`, `QUIET`, or `BLOCKED` in red with a ⛔ mark. `--status failed`, `--verdict blocked`, search by what happened inside (`--tool web`, `--tool-error`, `--agent`, `--model haiku`, `--min-tokens 50k`, `--min-secs 120`, or `--view <name>` for a saved one — `foldrun runs views` lists yours), `--outcome blocked,failed` (the dashboard's word; `needs-you` is `waiting`), `--since 24h`, `--to <workspace>`, `--limit <n>`. `--local` prints exactly what `logs --local` prints — this machine's runs, one workspace |
|
|
87
87
|
| `foldrun runs doctor <run-id>` | the run doctor: the assistant reads a failed run and the files it names, says why (platform, check, work or outside), and proposes the fix as diffs, saved on yes — the run page's **Doctor** (`--to`, `--yes`, `--dry-run`, `--json`). Charged like one assistant reply |
|
|
88
|
-
| `foldrun runs rm <run-id>` | erase a run from history: its record and its archived outputs. A run still in flight is stopped first. The ledger line stays — money is not deleted because a trace was. Asks first; `--yes` with no terminal |
|
|
88
|
+
| `foldrun runs rm <run-id>` | erase a run from history: its record and its archived outputs. A run still in flight is stopped first. The ledger line stays — money is not deleted because a trace was. Needs an admin (`workspace:manage`). Asks first; `--yes` with no terminal |
|
|
89
89
|
| `foldrun report <run-id>` | one run, whole, without opening the dashboard: the header, then every step with its group, agent, attempts, the runner image it ran on (`slim · browser pod` when it browsed through the account's pod from slim), cost, how much of its input the prompt cache served (`90% cached`; nothing for a step recorded before 18 Oct 2026) and, under a step that wrote a fifth or more of its input to the cache, why (`prompt cache: 75% of input written to the cache — memory changed since step 1`), how many model turns it took, duration, what happened to the browser pod under it (reconnects, `browser pod lost; re-ran on full` with its tries — `slim · lost` then `full` — or why it was not re-run), whether its `verify:` held and the first line of what it said — and for a failed step, the error and the last events before it. Then what it wrote, what it published and what is still waiting on a person. `--json` prints the run record instead |
|
|
90
90
|
| `foldrun report <run-id> --compare [<run-id>]` | this run beside the flow's [last good run](runs#compare-with-the-last-good-run), or the one named: whether they ran the same files and which changed, then what differs step by step (status, new errors, instruction, model, tools, time, tokens). `--json` |
|
|
91
91
|
| `foldrun report <run-id> --tree` | the run as [one tree](runs#the-trace-tree): each step, each model call (model, tokens, why it stopped) and each tool call under the call that asked for it, with how long each took and `← what went wrong` on the first failure. `--json` gives the tree and the failure path |
|
|
@@ -127,7 +127,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
127
127
|
| `foldrun invoke <flow>` | start a flow on a running platform — `--watch` follows its trace here; `--test` makes it a [test run](runs#test-runs) `--once <key>` sends the key as the run's idempotency key, so a CI step that retries after a dropped response is answered with the run it already started instead of paying for a second. `--tag <t>`, repeatable, labels the run (the API's `tags`). `--inputs <name>` sends a saved input set as the task — a case of `evals/<flow>-inputs.md` or of an eval that runs the flow, as the platform has it (see [Run with saved inputs](flows#run-with-saved-inputs)). `foldrun flow run <flow>` is the same command |
|
|
128
128
|
| `foldrun source <verb>` | one workspace file on a platform: `ls [dir]`, `cat <path>`, `put <path>` (from `--file`, else stdin; `--message` goes on the revision), `new <kind> <name>`, `mv <from> <to>`, `rm <path>` — the editor's own door, so every write is a revision. `new` is the dashboard's New button for any document (`POST …/assets { kind, name, agent?, template?, language? }`): `tools`, `knowledge`, `memory`, `skills`, `scripts` (and `agents`, `flows`, `evals`), the template written by the platform; `--agent <name>` puts a knowledge, memory, skill or script document inside that agent. For a whole tree, `deploy` |
|
|
129
129
|
| `foldrun open [page]` | the dashboard for this workspace, in the browser (`runs`, `agents`, `graph`, `repo`…) |
|
|
130
|
-
| `foldrun login` | sign this machine in from the browser — no key to copy |
|
|
130
|
+
| `foldrun login` | sign this machine in from the browser — no key to copy. Type the code it shows on the page and approve within five minutes |
|
|
131
131
|
| `foldrun login <site> --url <address>` | a browser window to sign in to a site by hand; the session is stored for an agent |
|
|
132
132
|
| `foldrun logout` | forget this machine's key, and revoke it if `login` made it |
|
|
133
133
|
| `foldrun whoami` | who you are on the platform: account, role, which workspaces |
|
|
@@ -141,7 +141,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
141
141
|
| `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`) |
|
|
142
142
|
| `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) |
|
|
143
143
|
| `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 |
|
|
144
|
-
| `foldrun storage <verb>` | what a workspace PRODUCED, as opposed to what you wrote — `source` is the other half. `ls [prefix]` lists every file with its size, when it was written, how long ago and which run wrote it (`run:<id>`, `user:<email>` for an upload, `api-key` for a key), newest first, plus what the store holds against its quota. `cat <path>` prints a text file and refuses one that is not text; `cat <path> --preview` asks the platform to read it instead and prints what is in it — a PDF or Word document as paragraphs, a spreadsheet or CSV as a table, a deck as slides, an archive as its listing. `get <path>` downloads it beside you — `--file <path>` names somewhere else, `--force` overwrites. `put <file|folder>...` uploads any files, of any type, into storage under their own names, walking folders whole (`.git`, `node_modules` and `.DS_Store` are skipped); `--into <folder/>` puts them under a folder, `--as <path>` renames a single file, and large files go straight to the bucket by a presigned URL, so size is not capped by the platform's request limit; `rm <path>` removes one. `share <path>` mints a public link to one produced file (7 days; `--ttl <days>`, `--forever`) and prints the URL; `shares` lists the live links (`--all` includes expired and revoked); `unshare <token>` revokes one — the link answers 404 from then on and the token is never reused. `--to <workspace>` from anywhere; inside a workspace folder it is already known |
|
|
144
|
+
| `foldrun storage <verb>` | what a workspace PRODUCED, as opposed to what you wrote — `source` is the other half. `ls [prefix]` lists every file with its size, when it was written, how long ago and which run wrote it (`run:<id>`, `user:<email>` for an upload, `api-key` for a key), newest first, plus what the store holds against its quota. `cat <path>` prints a text file and refuses one that is not text; `cat <path> --preview` asks the platform to read it instead and prints what is in it — a PDF or Word document as paragraphs, a spreadsheet or CSV as a table, a deck as slides, an archive as its listing. `get <path>` downloads it beside you — `--file <path>` names somewhere else, `--force` overwrites. `put <file|folder>...` uploads any files, of any type, into storage under their own names, walking folders whole (`.git`, `node_modules` and `.DS_Store` are skipped); `--into <folder/>` puts them under a folder, `--as <path>` renames a single file, and large files go straight to the bucket by a presigned URL, so size is not capped by the platform's request limit; `rm <path>` removes one. `share <path>` mints a public link to one produced file (7 days; `--ttl <days>`, `--forever`) and prints the URL; `shares` lists the live links (`--all` includes expired and revoked); `unshare <token|id>` revokes one — the link answers 404 from then on and the token is never reused. Only an admin, or the person who made a link, sees its token; anyone else sees the link with its token masked and an id (`sh_…`) to unshare it by. `--to <workspace>` from anywhere; inside a workspace folder it is already known |
|
|
145
145
|
| `foldrun runtimes` | the environments a deployed workspace's agents need — each distinct `runtime:` (an agent's own merged with its tools'), the packages in it, which agents use it, and whether the platform has built it: ready, building, or failed with the installer's own error. `foldrun deploy` prints the same thing after a deploy and waits up to two minutes for builds in progress (`--no-runtimes` skips the wait); this asks again later, and `--wait` holds on while any is building. Exits 1 when one has failed. `--to <workspace>` from anywhere |
|
|
146
146
|
| `foldrun schedule` | every flow in the account whose `trigger:` is a clock: workspace, flow, the cron line, its timezone, how many steps, whether the scheduler can parse it, and the next three times it fires. The times are the point — `0 5 1-7 * 5` reads as "the first Friday" and fires eight times in twenty-eight days, because day-of-month and day-of-week are OR'd. Exits 1 if any line is unparseable, since an invalid schedule errors nowhere and simply never runs. `--to <workspace>` narrows it |
|
|
147
147
|
| `foldrun schedule tick` | Settings' **Run scheduler now**: fire whatever is due this minute and print which flows went (`POST /api/schedule`). They were due anyway; this only makes them go now |
|
package/docs/flows.md
CHANGED
|
@@ -328,7 +328,7 @@ normal outcome, recorded as one.
|
|
|
328
328
|
| `after` / `on` | the flow to chain on, and whether on `completed` (default), `failed`, `blocked` or `any` |
|
|
329
329
|
| `path` | the `storage/` prefix to watch, for `trigger: storage` |
|
|
330
330
|
| `url` / `every` | what to poll and how often (default 15m), for `trigger: watch` |
|
|
331
|
-
| `signature` / `signing_secret` | `github` \| `stripe` \| `slack` \| `hmac`, and the vault entry to check it against |
|
|
331
|
+
| `signature` / `signing_secret` | `github` \| `stripe` \| `slack` \| `hmac`, and the NAME of the vault entry to check it against — never the value (`foldrun check` warns: [secret/signing-secret-value](checks#secret-signing-secret-value)) |
|
|
332
332
|
| `filter` | for a `webhook`, `email`, `flow` or `storage` trigger: the fields a delivery must have to start a run — see [Which deliveries start a run](#which-deliveries-start-a-run) |
|
|
333
333
|
| `model` / `effort` | defaults for every step |
|
|
334
334
|
| `budget` | the most one run may spend, in USD — a number, or `unlimited`; unset is no limit |
|
package/docs/notifications.md
CHANGED
|
@@ -24,6 +24,14 @@ notify:
|
|
|
24
24
|
|
|
25
25
|
A bare string is whichever destination it looks like: `notify: ops@example.com`.
|
|
26
26
|
|
|
27
|
+
`${NAME}` is filled from the vault, the workspace's first and then the
|
|
28
|
+
account's, as for an agent. A secret [bound to sites](secrets#bound-to-sites)
|
|
29
|
+
is filled only when the URL's host is one of them — bind `SLACK_WEBHOOK_URL`
|
|
30
|
+
to `hooks.slack.com` and it goes there and nowhere else; named in a URL to
|
|
31
|
+
any other host, nothing is sent and the delivery log says which secret
|
|
32
|
+
stopped it. A URL that carries a secret follows a redirect only within its
|
|
33
|
+
own origin.
|
|
34
|
+
|
|
27
35
|
A webhook can also be signed, so the receiver can tell a real notification
|
|
28
36
|
from anyone who learned the URL:
|
|
29
37
|
|
|
@@ -167,7 +175,8 @@ destination and reports what came back, including the provider's own words
|
|
|
167
175
|
on a failure. Those words are the value: "domain not verified" and "you can
|
|
168
176
|
only send to your own address" send you to two different pages, and a status
|
|
169
177
|
code sends you to neither. `POST /api/workspaces/<ws>/notify/test` is the
|
|
170
|
-
same thing.
|
|
178
|
+
same thing. A workspace gets 10 test sends an hour; past that the button
|
|
179
|
+
says to wait.
|
|
171
180
|
|
|
172
181
|
## Where it is set, and the rule that bites
|
|
173
182
|
|
package/docs/runs.md
CHANGED
|
@@ -304,7 +304,9 @@ run until a person decides. Three doors open it, and the trace says which:
|
|
|
304
304
|
- **the emailed link** — the notification carries approve and reject links
|
|
305
305
|
when the install has a public URL;
|
|
306
306
|
- **an external event** — a `wait: event` step is released by a POST to the
|
|
307
|
-
|
|
307
|
+
event URL printed in its trace, and what was posted reaches the next step.
|
|
308
|
+
The URL is that step's, for that one wait: it does not release a later
|
|
309
|
+
`wait: event` of the same run, and once used it answers `409`. A person can
|
|
308
310
|
release it the same way from the run page (or `approve` with a `payload`):
|
|
309
311
|
the payload reaches the step just the same, and the trace names them, not
|
|
310
312
|
"an external event". The approvers and self-approval rules below are for
|
package/docs/secrets.md
CHANGED
|
@@ -72,6 +72,57 @@ Put a credential at the account when every workspace should use the same one
|
|
|
72
72
|
— your model provider, your email sender. Put it in a workspace when it is
|
|
73
73
|
that job's — a customer's Search Console, a CRM key.
|
|
74
74
|
|
|
75
|
+
### Limited to some workspaces
|
|
76
|
+
|
|
77
|
+
An account secret is open to every workspace by default. To share one
|
|
78
|
+
credential with a few workspaces but not the rest — the way GitHub limits an
|
|
79
|
+
organisation secret to selected repositories — limit it:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
foldrun secrets set STRIPE_KEY --account --workspaces sales,billing # a new one, limited from the start
|
|
83
|
+
foldrun secrets workspaces STRIPE_KEY sales billing # only these two
|
|
84
|
+
foldrun secrets workspaces STRIPE_KEY # which may use it
|
|
85
|
+
foldrun secrets workspaces STRIPE_KEY --none # no workspace
|
|
86
|
+
foldrun secrets workspaces STRIPE_KEY --all # every workspace again
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
In the dashboard it is **Workspaces: all / selected** on the secret's row in
|
|
90
|
+
Settings → Secrets, and on the form that adds one; over the API,
|
|
91
|
+
`PATCH /api/secrets { name, workspaces }` (`null` for every workspace, `[]`
|
|
92
|
+
for none), or `workspaces` on the `PUT` that stores the value. Given with the
|
|
93
|
+
value, the two are saved in one write: the secret is never open to every
|
|
94
|
+
workspace in between. "All" includes workspaces made later. Every other workspace finds the
|
|
95
|
+
secret **not set**, exactly as if it had never been stored: a run reports it
|
|
96
|
+
missing, a tool test and a `notify:` or `telemetry:` header leave
|
|
97
|
+
`${NAME}` unfilled, the egress proxy has nothing to fill, an MCP server does
|
|
98
|
+
not get it, a notification email it sends does not go out through the
|
|
99
|
+
account's `RESEND_API_KEY` or `EMAIL_FROM` (the platform's sender is used, if
|
|
100
|
+
there is one), and the workspace's secret list and the editor's completions
|
|
101
|
+
leave it out. A workspace's own secret of the same name still works there.
|
|
102
|
+
|
|
103
|
+
A limit applies to runs that **start after it**. A run already going keeps
|
|
104
|
+
what it was given when it started — values in its sandbox, and the ones the
|
|
105
|
+
egress proxy fills for it — so stop a running one to cut it off at once.
|
|
106
|
+
|
|
107
|
+
The names must be workspaces that exist. Renaming a workspace carries its
|
|
108
|
+
place on every list; deleting one takes it off first, so a new workspace
|
|
109
|
+
given the old name inherits nothing. If a secret limited to it cannot be read
|
|
110
|
+
with the platform's keys, the rename or delete is refused and names it — set
|
|
111
|
+
it again or delete it, then try again. Only an admin with access to every
|
|
112
|
+
workspace sets the limit, and the account's `RESEND_API_KEY` and `EMAIL_FROM`
|
|
113
|
+
stay the owner's. The account's own uses of a secret — its model key in
|
|
114
|
+
Settings → Model, and the mail the platform sends for the account (password
|
|
115
|
+
resets, invites, billing) — are not a workspace's and are not limited. A new
|
|
116
|
+
value or a new site binding keeps the limit. Limiting a secret seals the list
|
|
117
|
+
with the value, like `sites` (see [How they are kept](#how-they-are-kept)),
|
|
118
|
+
whatever form the secret was stored in before: a list changed on disk makes
|
|
119
|
+
the secret unreadable, never open to everyone.
|
|
120
|
+
|
|
121
|
+
On a platform you run yourself, set limits only once every pod — web,
|
|
122
|
+
worker and egress proxy — runs a version that has them: an older one cannot
|
|
123
|
+
read a limited secret, and one that stores a new value over it drops the
|
|
124
|
+
limit.
|
|
125
|
+
|
|
75
126
|
## How an agent gets it
|
|
76
127
|
|
|
77
128
|
```yaml
|
package/docs/security.md
CHANGED
|
@@ -167,21 +167,48 @@ Signing in, in particular:
|
|
|
167
167
|
- a password reset or change, two-step sign-in turned on or off, and a new
|
|
168
168
|
API key each send a notice to the person's address;
|
|
169
169
|
- signing out ends the session on the server, not just in the browser;
|
|
170
|
+
- changing your password or login address, or turning two-step sign-in
|
|
171
|
+
on, signs out every other browser;
|
|
170
172
|
- a two-step code works once; replacing a second factor means turning it
|
|
171
173
|
off first, which needs the password and a code;
|
|
174
|
+
- wrong passwords are counted per account and per caller: someone failing
|
|
175
|
+
as you locks out only their own address, never yours; a guesser spread
|
|
176
|
+
over many addresses meets a ceiling for the account, and you are mailed
|
|
177
|
+
when it is reached (this needs `FOLDRUN_TRUST_PROXY`, so callers can be
|
|
178
|
+
told apart — without it the count is per account, from anyone);
|
|
179
|
+
- a password reset mails at most three links an hour to one address, and
|
|
180
|
+
one caller can use at most a small share of the install's hourly reset
|
|
181
|
+
mail, so nobody can spend everyone else's;
|
|
182
|
+
- ten wrong two-step codes in a row pause codes from the app for up to a
|
|
183
|
+
day and mail the person — a backup code still signs in, and the pause
|
|
184
|
+
lifts by itself;
|
|
185
|
+
- changing your login address only mails the new address a link, and the
|
|
186
|
+
move happens when that link is clicked; asking answers the same whether
|
|
187
|
+
or not the address already has a login, so it cannot be used to find out
|
|
188
|
+
who has an account. An install that can send no mail refuses the change
|
|
189
|
+
until mail is set up, rather than moving the login unconfirmed;
|
|
172
190
|
- the sign-in forms refuse a request from another site, and `?next=` only
|
|
173
191
|
ever leads to a page on the same site;
|
|
174
192
|
- `foldrun login` asks you to type the code your terminal shows — a link
|
|
175
193
|
with the code in it, sent by someone else, cannot sign their machine in
|
|
176
|
-
as you
|
|
194
|
+
as you. The page shows when and from which network the terminal asked,
|
|
195
|
+
warns when that is not the network you are on, and a request more than
|
|
196
|
+
five minutes old can no longer be approved;
|
|
177
197
|
- before the first sign-up, a self-hosted install's setup token guards key
|
|
178
198
|
minting as it guards sign-up;
|
|
179
|
-
- only the account's owner can set the account's
|
|
180
|
-
`EMAIL_FROM`, because that sender carries everyone's
|
|
199
|
+
- only the account's owner can set, rebind or remove the account's
|
|
200
|
+
`RESEND_API_KEY` and `EMAIL_FROM`, because that sender carries everyone's
|
|
201
|
+
reset links — whether through the secrets API or an OAuth connect. The
|
|
202
|
+
owner means the owner in person: their signed-in session, or the key
|
|
203
|
+
their own `foldrun login` made. Any other key they minted (CI, a key
|
|
204
|
+
handed to a contractor) is refused;
|
|
205
|
+
- a key rotated by a caller that is no person (a key known only by its
|
|
206
|
+
label) acts as nobody, never as the rotated key's owner;
|
|
181
207
|
- a member or key limited to some workspaces cannot change what every
|
|
182
208
|
workspace shares — the library, the account's AGENTS.md defaults, its
|
|
183
|
-
model provider, its OAuth apps — nor people who work
|
|
184
|
-
workspaces
|
|
209
|
+
model provider, its OAuth apps, the API version pin — nor people who work
|
|
210
|
+
outside its workspaces, and does not read the other workspaces' provider
|
|
211
|
+
blocks or charges, nor the account's billing details.
|
|
185
212
|
|
|
186
213
|
Frontmatter is YAML only: a file opened with `---js` (which some parsers
|
|
187
214
|
run as code) is refused.
|
|
@@ -30,6 +30,16 @@ Both are platform settings (`FOLDRUN_STORAGE_MAX_MB`,
|
|
|
30
30
|
`FOLDRUN_STORAGE_QUOTA_MB`). Storage is metered per GB-month where billing is
|
|
31
31
|
on.
|
|
32
32
|
|
|
33
|
+
Both limits hold for a direct upload too. An upload asks for its URL with the
|
|
34
|
+
file's length (`POST …/storage/upload-url` with `path`, `sha`, `size`); the
|
|
35
|
+
limits are checked then, and the length is signed into the URL, so the bucket
|
|
36
|
+
refuses a body of any other length. Recording the file afterwards measures
|
|
37
|
+
the object the bucket holds; the record, the limit and the quota use that,
|
|
38
|
+
never the length the client claimed, and an object over a limit is removed.
|
|
39
|
+
|
|
40
|
+
Storage belongs to a workspace that exists: a name with no workspace is a
|
|
41
|
+
`404`, never a fresh, empty store.
|
|
42
|
+
|
|
33
43
|
## Under the hood
|
|
34
44
|
|
|
35
45
|
Blobs are content-addressed and go to object storage (S3-compatible — R2, S3
|
|
@@ -56,7 +66,7 @@ the terminal:
|
|
|
56
66
|
```
|
|
57
67
|
foldrun storage share cover.jpg --to <ws> # 7 days; --ttl 30, or --forever
|
|
58
68
|
foldrun storage shares --to <ws> # live links; --all shows expired and revoked
|
|
59
|
-
foldrun storage unshare <token> --to <ws>
|
|
69
|
+
foldrun storage unshare <token|id> --to <ws>
|
|
60
70
|
```
|
|
61
71
|
|
|
62
72
|
- Links expire in **7 days** unless you say otherwise; `null` never expires.
|
|
@@ -66,6 +76,16 @@ foldrun storage unshare <token> --to <ws>
|
|
|
66
76
|
into sharing is confined to what the workspace produced and can never hand
|
|
67
77
|
out `memory/`, a prompt, or a credential.
|
|
68
78
|
- Revoking is permanent; a re-share mints a new token.
|
|
79
|
+
- Revoking takes effect at once: a link is served `Cache-Control: private,
|
|
80
|
+
no-store`, so no CDN keeps answering it after a revoke or its expiry.
|
|
81
|
+
- Only an admin, or the person who made a link, sees its token and can copy
|
|
82
|
+
it. Everyone else sees that the file is shared, by whom and until when;
|
|
83
|
+
an editor can still revoke it (by its id).
|
|
84
|
+
- Deleting a workspace revokes its links and deletes its stored files.
|
|
85
|
+
Renaming one moves both: its links keep working, under the new name.
|
|
86
|
+
- A link answers at most 120 requests a minute to one caller (where a trusted
|
|
87
|
+
proxy names the caller) and 1,200 a minute in all, then `429` with
|
|
88
|
+
`Retry-After`. The file is streamed, never read whole into memory.
|
|
69
89
|
|
|
70
90
|
Files written under **`storage/public/`** get a link automatically after the
|
|
71
91
|
run — for the agent that needs a URL for what it just produced.
|
package/docs/team-and-access.md
CHANGED
|
@@ -10,17 +10,38 @@ whose supervisors cannot see what the agents did is not supervised.
|
|
|
10
10
|
| role | may |
|
|
11
11
|
|---|---|
|
|
12
12
|
| **viewer** | read everything — workspaces, runs and their output, files, history, usage |
|
|
13
|
-
| **editor** | + edit files, upload, deploy, push; run, stop, re-run, approve and promote runs; test tools |
|
|
14
|
-
| **admin** | + create and delete workspaces; write secrets and connect credentials; mint keys; invite, re-role and remove editors and viewers |
|
|
13
|
+
| **editor** | + edit files, upload, deploy (to a workspace that exists — a deploy that makes one is an admin's), push; run, stop, re-run, approve and promote runs; test tools |
|
|
14
|
+
| **admin** | + create and delete workspaces; delete a run from history; write secrets and connect credentials; mint keys; invite, re-role and remove editors and viewers |
|
|
15
15
|
| **owner** | + billing; make and unmake admins; transfer the account |
|
|
16
16
|
|
|
17
17
|
There is exactly one owner: the account's creator until they transfer it.
|
|
18
|
-
|
|
18
|
+
Transferring asks for the owner's password again, and a code from their app
|
|
19
|
+
when two-step sign-in is on — a session left open is not enough to give the
|
|
20
|
+
account away. The owner is never re-roled or removed — transfer first. Nobody changes their
|
|
19
21
|
own role, and an admin cannot make or remove another admin: an admin who can
|
|
20
22
|
promote peers is an owner with extra steps.
|
|
21
23
|
|
|
22
24
|
A refused call answers `403` with the role that was needed.
|
|
23
25
|
|
|
26
|
+
### A workspace's policy is an admin's
|
|
27
|
+
|
|
28
|
+
The keys in a workspace's `AGENTS.md` that set policy for the whole
|
|
29
|
+
workspace — `budget`, `compute`, `notify`, `network_enforce`, `telemetry`,
|
|
30
|
+
`alerts`, `owner`, `judge` and `timezone` (also when written under a
|
|
31
|
+
`governance:`, `guardrail:`, `observability:` or `evaluation:` block) — need
|
|
32
|
+
the **admin** role to change, whichever way the file is written: the
|
|
33
|
+
workspace's settings, a save in the editor (`PUT …/source`), `foldrun deploy`,
|
|
34
|
+
an import, or a restore to an older point. An editor still edits the rest of
|
|
35
|
+
`AGENTS.md` — its prose and every other key — and may deploy, import or
|
|
36
|
+
restore anything that leaves those keys as they are; a change to one of them
|
|
37
|
+
is refused with a `403` that names the key, and nothing is written. Removing
|
|
38
|
+
the file, or saving one whose frontmatter does not parse, drops the keys, so
|
|
39
|
+
it counts as a change too. A dry run (deploy, import, restore) is not
|
|
40
|
+
refused.
|
|
41
|
+
|
|
42
|
+
The account's own `AGENTS.md` is written only through the account's settings
|
|
43
|
+
(`PATCH /api/account`), which needs an admin with access to every workspace.
|
|
44
|
+
|
|
24
45
|
## Scoped members
|
|
25
46
|
|
|
26
47
|
A member can be limited to some workspaces. The customer whose desk lives in
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "10.1.0",
|
|
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",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"node": ">=22"
|
|
12
12
|
},
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@foldrun/core": "^
|
|
14
|
+
"@foldrun/core": "^9.0.0"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
17
|
"bin",
|
package/src/commands.mjs
CHANGED
|
@@ -3270,6 +3270,82 @@ async function localSetSites(name, sites, scope) {
|
|
|
3270
3270
|
return k.setSecretSites("default", name, sites, scope);
|
|
3271
3271
|
}
|
|
3272
3272
|
|
|
3273
|
+
/** The workspaces this machine's vault serves: an account folder's, or the
|
|
3274
|
+
* one folder a flat workspace is — what a local limit may name, as the
|
|
3275
|
+
* platform allows only workspaces that exist. */
|
|
3276
|
+
function localWorkspaceNames(layout) {
|
|
3277
|
+
if (layout?.kind === "account") return layout.workspaces;
|
|
3278
|
+
return [path.basename(process.env.FOLDRUN_WORKSPACE ?? process.cwd())];
|
|
3279
|
+
}
|
|
3280
|
+
|
|
3281
|
+
/** A core from before the limit would take the list as an argument it does
|
|
3282
|
+
* not know and store the secret open to every workspace: refused instead.
|
|
3283
|
+
* Typed loosely: the installed core's types may predate the limit, which is
|
|
3284
|
+
* exactly the case the check below refuses at run time.
|
|
3285
|
+
* @returns {Promise<any>} */
|
|
3286
|
+
async function limitingCore() {
|
|
3287
|
+
/** @type {any} */
|
|
3288
|
+
const k = await core();
|
|
3289
|
+
if (typeof k.setSecretWorkspaces !== "function") throw new Error("limiting a secret to workspaces needs a newer @foldrun/core — update foldrun");
|
|
3290
|
+
return k;
|
|
3291
|
+
}
|
|
3292
|
+
|
|
3293
|
+
/** Limit an account secret on this machine's vault. */
|
|
3294
|
+
async function localSetWorkspaces(name, workspaces, layout) {
|
|
3295
|
+
const known = localWorkspaceNames(layout);
|
|
3296
|
+
return (await limitingCore()).setSecretWorkspaces("default", name, workspaces, { exists: (w) => known.includes(w) });
|
|
3297
|
+
}
|
|
3298
|
+
|
|
3299
|
+
/** `--workspaces a,b` (or `--none`) on `secrets set`: the limit sent with
|
|
3300
|
+
* the value, so the secret is never open to every workspace in between.
|
|
3301
|
+
* Undefined when neither was given. */
|
|
3302
|
+
function workspacesFlag(flags) {
|
|
3303
|
+
if (flags.none === true && flags.workspaces !== undefined) throw new Error("either --workspaces or --none, not both");
|
|
3304
|
+
if (flags.none === true) return [];
|
|
3305
|
+
if (flags.workspaces === undefined) return undefined;
|
|
3306
|
+
if (typeof flags.workspaces !== "string") throw new Error("--workspaces takes the names: --workspaces sales,ops");
|
|
3307
|
+
const list = flags.workspaces.split(",").map((v) => v.trim()).filter(Boolean);
|
|
3308
|
+
if (!list.length) throw new Error("--workspaces takes the names: --workspaces sales,ops (--none for no workspace)");
|
|
3309
|
+
return list;
|
|
3310
|
+
}
|
|
3311
|
+
|
|
3312
|
+
/**
|
|
3313
|
+
* `foldrun secrets workspaces NAME [workspace…] [--all | --none]` — which
|
|
3314
|
+
* workspaces may use an ACCOUNT secret: every one (the default), only those
|
|
3315
|
+
* named (GitHub's "selected repositories" for an organisation secret), or
|
|
3316
|
+
* none. Every other workspace finds it not set. No names and no flag prints
|
|
3317
|
+
* what it is now. On the platform (PATCH /api/secrets { name, workspaces },
|
|
3318
|
+
* an admin over every workspace), or this machine's vault with --local —
|
|
3319
|
+
* where, as on the platform, only workspaces that exist may be named.
|
|
3320
|
+
*/
|
|
3321
|
+
async function secretWorkspacesCmd(args, flags, url, layout) {
|
|
3322
|
+
const [name, ...rest] = args;
|
|
3323
|
+
if (!name) throw new Error("which secret? `foldrun secrets workspaces NAME [workspace …]`, `--all` for every workspace, `--none` for none");
|
|
3324
|
+
const named = rest.flatMap((v) => v.split(",")).map((v) => v.trim()).filter(Boolean);
|
|
3325
|
+
if ([flags.all === true, flags.none === true, named.length > 0].filter(Boolean).length > 1) {
|
|
3326
|
+
throw new Error("one of: workspace names, --all, or --none");
|
|
3327
|
+
}
|
|
3328
|
+
const describe = (list) =>
|
|
3329
|
+
list === null || list === undefined
|
|
3330
|
+
? `${c.bold(name)} may be used in every workspace`
|
|
3331
|
+
: list.length
|
|
3332
|
+
? `${c.bold(name)} may be used only in ${list.join(", ")} — every other workspace finds it not set`
|
|
3333
|
+
: `${c.bold(name)} may be used in no workspace`;
|
|
3334
|
+
if (!named.length && flags.all !== true && flags.none !== true) {
|
|
3335
|
+
const entries = url ? (await remoteCall(url, flags, "/api/secrets")).secrets : (await core()).listSecrets("default");
|
|
3336
|
+
const hit = entries.find((s) => s.name === name && s.scope === "account");
|
|
3337
|
+
if (!hit) throw new Error(`no secret ${name} in the account — this limits an account secret; a workspace's own is that workspace's already`);
|
|
3338
|
+
console.log(`\n ${describe(hit.workspaces)}${hit.workspaces ? "" : c.dim(` — limit it: foldrun secrets workspaces ${name} <workspace> …`)}\n`);
|
|
3339
|
+
return 0;
|
|
3340
|
+
}
|
|
3341
|
+
const workspaces = flags.all === true ? null : flags.none === true ? [] : named;
|
|
3342
|
+
const stored = url
|
|
3343
|
+
? (await remoteCall(url, flags, "/api/secrets", { method: "PATCH", body: JSON.stringify({ name, workspaces }) })).workspaces
|
|
3344
|
+
: await localSetWorkspaces(name, workspaces, layout);
|
|
3345
|
+
console.log(`\n ${c.green("✓")} ${describe(stored)}\n`);
|
|
3346
|
+
return 0;
|
|
3347
|
+
}
|
|
3348
|
+
|
|
3273
3349
|
/** `--site a.com --site "*.b.org"` or `--site a.com,b.org`, as one list. */
|
|
3274
3350
|
function siteFlags(flags) {
|
|
3275
3351
|
const raw = flags.site === undefined ? [] : Array.isArray(flags.site) ? flags.site : [flags.site];
|
|
@@ -3281,6 +3357,9 @@ async function secretsCmd(positional, flags, layout) {
|
|
|
3281
3357
|
// hatch deploy and keys have. Without it, a signed-in laptop sent every
|
|
3282
3358
|
// secret to the platform and the local store could not be reached at all.
|
|
3283
3359
|
const url = flags.local === true ? undefined : remoteUrl(flags);
|
|
3360
|
+
// An account secret's workspaces: always the account's store, so no
|
|
3361
|
+
// workspace is asked for (or taken from the folder).
|
|
3362
|
+
if (positional[0] === "workspaces") return secretWorkspacesCmd(positional.slice(1), flags, url, layout);
|
|
3284
3363
|
// The scope is the workspace's own store, named the way the runner names
|
|
3285
3364
|
// it — the folder's basename. It was the literal string "workspace", so a
|
|
3286
3365
|
// secret set from the terminal landed under workspaces/workspace/ and every
|
|
@@ -3306,7 +3385,7 @@ async function secretsCmd(positional, flags, layout) {
|
|
|
3306
3385
|
console.log();
|
|
3307
3386
|
for (const s of entries) {
|
|
3308
3387
|
console.log(
|
|
3309
|
-
` ${c.bold(s.name)} ${c.dim(`${s.scope}${s.shadowed ? " · shadowed" : ""} · ${s.updatedAt ?? ""}${s.sites?.length ? ` · sent only to ${s.sites.join(", ")}` : ""}`)}`,
|
|
3388
|
+
` ${c.bold(s.name)} ${c.dim(`${s.scope}${s.shadowed ? " · shadowed" : ""} · ${s.updatedAt ?? ""}${s.sites?.length ? ` · sent only to ${s.sites.join(", ")}` : ""}${Array.isArray(s.workspaces) ? ` · ${s.workspaces.length ? `only in ${s.workspaces.join(", ")}` : "in no workspace"}` : ""}`)}`,
|
|
3310
3389
|
);
|
|
3311
3390
|
}
|
|
3312
3391
|
console.log();
|
|
@@ -3367,12 +3446,26 @@ async function secretsCmd(positional, flags, layout) {
|
|
|
3367
3446
|
}
|
|
3368
3447
|
|
|
3369
3448
|
if (verb === "set") {
|
|
3449
|
+
// --workspaces a,b / --none: an ACCOUNT secret limited to those
|
|
3450
|
+
// workspaces, sent with the value so it is never open in between.
|
|
3451
|
+
const limitTo = workspacesFlag(flags);
|
|
3452
|
+
if (limitTo !== undefined && scope) throw new Error("--workspaces limits an account secret — add --account (a workspace's own secret is that workspace's already)");
|
|
3453
|
+
const withLimit = limitTo !== undefined ? { workspaces: limitTo } : {};
|
|
3454
|
+
/** @returns {Promise<{ k: any, limit: object }>} — typed loosely, as limitingCore is. */
|
|
3455
|
+
const localLimit = async () => {
|
|
3456
|
+
if (limitTo === undefined) return { k: await core(), limit: {} };
|
|
3457
|
+
const known = localWorkspaceNames(layout);
|
|
3458
|
+
return { k: await limitingCore(), limit: { workspaces: limitTo, exists: (w) => known.includes(w) } };
|
|
3459
|
+
};
|
|
3370
3460
|
// --kind: the other shapes the Connections form stores — a file, an SSH
|
|
3371
3461
|
// login, API headers, a service account's key, a client-credentials app.
|
|
3372
3462
|
if (typeof flags.kind === "string") {
|
|
3373
3463
|
const { body, local } = await secretOfKind(flags.kind, flags);
|
|
3374
|
-
if (url) await remoteCall(url, flags, "/api/secrets", { method: "PUT", body: JSON.stringify({ name, ...body, workspace: scope }) });
|
|
3375
|
-
else
|
|
3464
|
+
if (url) await remoteCall(url, flags, "/api/secrets", { method: "PUT", body: JSON.stringify({ name, ...body, workspace: scope, ...withLimit }) });
|
|
3465
|
+
else {
|
|
3466
|
+
const { k, limit } = await localLimit();
|
|
3467
|
+
local(k, name, body, scope, limit);
|
|
3468
|
+
}
|
|
3376
3469
|
console.log(`\n ${c.green("✓")} ${name} stored as ${flags.kind}${url ? "" : " on this machine"} — declare it in agent.md under \`secrets:\` to use it\n`);
|
|
3377
3470
|
return 0;
|
|
3378
3471
|
}
|
|
@@ -3389,10 +3482,11 @@ async function secretsCmd(positional, flags, layout) {
|
|
|
3389
3482
|
if (url) {
|
|
3390
3483
|
await remoteCall(url, flags, "/api/secrets", {
|
|
3391
3484
|
method: "PUT",
|
|
3392
|
-
body: JSON.stringify({ name, oauth2: config, workspace: scope }),
|
|
3485
|
+
body: JSON.stringify({ name, oauth2: config, workspace: scope, ...withLimit }),
|
|
3393
3486
|
});
|
|
3394
3487
|
} else {
|
|
3395
|
-
|
|
3488
|
+
const { k, limit } = await localLimit();
|
|
3489
|
+
k.setOAuth2Secret("default", name, config, scope, limit);
|
|
3396
3490
|
}
|
|
3397
3491
|
console.log(`\n ${c.green("✓")} ${name} stored as an auto-refreshing oauth2 credential\n`);
|
|
3398
3492
|
return 0;
|
|
@@ -3405,14 +3499,15 @@ async function secretsCmd(positional, flags, layout) {
|
|
|
3405
3499
|
if (url) {
|
|
3406
3500
|
await remoteCall(url, flags, "/api/secrets", {
|
|
3407
3501
|
method: "PUT",
|
|
3408
|
-
body: JSON.stringify({ name, value, workspace: scope, ...(sites.length ? { sites } : {}) }),
|
|
3502
|
+
body: JSON.stringify({ name, value, workspace: scope, ...(sites.length ? { sites } : {}), ...withLimit }),
|
|
3409
3503
|
});
|
|
3410
3504
|
} else {
|
|
3411
|
-
const k = await
|
|
3412
|
-
k.setSecret("default", name, value, scope);
|
|
3505
|
+
const { k, limit } = await localLimit();
|
|
3506
|
+
k.setSecret("default", name, value, scope, undefined, limit);
|
|
3413
3507
|
if (sites.length) await localSetSites(name, sites, scope);
|
|
3414
3508
|
}
|
|
3415
|
-
|
|
3509
|
+
const limited = limitTo === undefined ? "" : limitTo.length ? `, only for ${limitTo.join(", ")}` : ", for no workspace yet";
|
|
3510
|
+
console.log(`\n ${c.green("✓")} ${name} stored${sites.length ? ` and sent only to ${sites.join(", ")}` : ""}${limited} — declare it in agent.md under \`secrets:\` to use it\n`);
|
|
3416
3511
|
return 0;
|
|
3417
3512
|
}
|
|
3418
3513
|
|
|
@@ -3975,7 +4070,9 @@ async function login(flags) {
|
|
|
3975
4070
|
console.log(`\n Confirm this code in your browser: ${c.bold(start.code)}\n`);
|
|
3976
4071
|
console.log(` ${c.dim(start.verifyUrl)}\n`);
|
|
3977
4072
|
const opened = flags["no-browser"] === true ? false : await openInBrowser(start.verifyUrl);
|
|
3978
|
-
|
|
4073
|
+
// The platform refuses to approve a request older than five minutes
|
|
4074
|
+
// (RFC 8628 §5.4: a code someone else started and sent goes stale).
|
|
4075
|
+
console.log(` ${c.dim(opened ? "Opening the browser… waiting for you to approve (within five minutes)." : "Open that address on any device and enter the code within five minutes. Waiting…")}`);
|
|
3979
4076
|
|
|
3980
4077
|
const interval = Math.max(1, Number(start.interval) || 3) * 1000;
|
|
3981
4078
|
const deadline = Date.parse(start.expiresAt) || Date.now() + 10 * 60 * 1000;
|
|
@@ -5248,20 +5345,23 @@ async function storageCmd(positional, flags, layout) {
|
|
|
5248
5345
|
console.log(`\n ${c.dim(`no ${flags.all === true ? "" : "live "}links in ${ws} — \`foldrun storage share <path>\` mints one${flags.all === true ? "" : ", --all shows expired and revoked ones too"}`)}\n`);
|
|
5249
5346
|
return 0;
|
|
5250
5347
|
}
|
|
5251
|
-
|
|
5348
|
+
// Only an admin, or a link's own maker, is handed its token (30 Oct
|
|
5349
|
+
// 2026); anyone else gets it masked, with an id to unshare it by.
|
|
5350
|
+
const handle = (x) => (x.masked && x.id ? x.id : x.token);
|
|
5351
|
+
const w = { path: Math.max(...rows.map((x) => x.path.length)), token: Math.max(...rows.map((x) => handle(x).length)) };
|
|
5252
5352
|
console.log();
|
|
5253
5353
|
for (const x of rows) {
|
|
5254
5354
|
const state = x.revokedAt ? c.red(`revoked ${ago(x.revokedAt)} ago`) : !live(x) ? c.red(`expired ${ago(x.expiresAt)} ago`) : x.expiresAt ? `until ${when(x.expiresAt)}` : "never expires";
|
|
5255
|
-
console.log(` ${live(x) ? c.green("✓") : c.dim("·")} ${c.bold(pad(x.path, w.path))} ${c.dim(pad(x
|
|
5355
|
+
console.log(` ${live(x) ? c.green("✓") : c.dim("·")} ${c.bold(pad(x.path, w.path))} ${c.dim(pad(handle(x), w.token))} ${c.dim(`${state} · by ${x.createdBy ?? "api-key"} · ${ago(x.createdAt)} ago`)}`);
|
|
5256
5356
|
}
|
|
5257
|
-
console.log(`\n ${c.dim(`${rows.length} link${rows.length === 1 ? "" : "s"} · a link is <platform>/s/<token> · \`foldrun storage unshare <token> --to ${ws}\``)}\n`);
|
|
5357
|
+
console.log(`\n ${c.dim(`${rows.length} link${rows.length === 1 ? "" : "s"} · a link is <platform>/s/<token> · \`foldrun storage unshare <token|id> --to ${ws}\``)}\n`);
|
|
5258
5358
|
return 0;
|
|
5259
5359
|
}
|
|
5260
5360
|
if (verb === "unshare") {
|
|
5261
5361
|
const token = positional[1];
|
|
5262
|
-
if (!token) throw new Error("`foldrun storage unshare <token>` — `foldrun storage shares` lists them");
|
|
5362
|
+
if (!token) throw new Error("`foldrun storage unshare <token|id>` — `foldrun storage shares` lists them (an id, sh_…, where the token is not yours to see)");
|
|
5263
5363
|
if (!(await sureToDelete(flags, "storage unshare", `share link ${token} (anyone holding it gets 404)`))) return 1;
|
|
5264
|
-
const { revoked } = await remoteCall(url, flags, `/api/workspaces/${ws}/shares?token=${encodeURIComponent(token)}`, { method: "DELETE" });
|
|
5364
|
+
const { revoked } = await remoteCall(url, flags, `/api/workspaces/${ws}/shares?${token.startsWith("sh_") ? "id" : "token"}=${encodeURIComponent(token)}`, { method: "DELETE" });
|
|
5265
5365
|
if (!revoked) {
|
|
5266
5366
|
console.log(`\n ${c.dim(`nothing revoked — ${token} is not a live link of this account's`)}\n`);
|
|
5267
5367
|
return 1;
|
|
@@ -5316,7 +5416,9 @@ async function storageCmd(positional, flags, layout) {
|
|
|
5316
5416
|
}
|
|
5317
5417
|
try {
|
|
5318
5418
|
const sha = crypto.createHash("sha256").update(bytes).digest("hex");
|
|
5319
|
-
|
|
5419
|
+
// The length too: the platform checks the limits on it and signs it
|
|
5420
|
+
// into the URL, so the bucket takes exactly these bytes (30 Oct 2026).
|
|
5421
|
+
const ask = await remoteFetch(url, `${base}/upload-url`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ path: rel, sha, size: bytes.length }) }, { token });
|
|
5320
5422
|
// A platform older than presigned uploads answers 404 here: it
|
|
5321
5423
|
// takes the bytes itself, the way one with no bucket does.
|
|
5322
5424
|
if (!ask.ok && ask.status !== 404) throw new HttpError(await said(ask), ask.status, {});
|
|
@@ -5734,10 +5836,14 @@ async function billingCmd(flags) {
|
|
|
5734
5836
|
/** The events a notify block may name, as the platform validates them. */
|
|
5735
5837
|
const NOTIFY_EVENTS = ["failed", "awaiting-approval", "completed"];
|
|
5736
5838
|
|
|
5839
|
+
/** Why a caller limited to some workspaces sees "set" for the account's
|
|
5840
|
+
* notify: URL or telemetry: (GET /api/account answers `hidden: true`). */
|
|
5841
|
+
const HIDDEN_NOTE = "where it goes is shown only to a member or key with every workspace";
|
|
5842
|
+
|
|
5737
5843
|
/** The account's defaults, as one readable block. */
|
|
5738
5844
|
function printDefaults(d) {
|
|
5739
5845
|
const notify = d.notify
|
|
5740
|
-
? [d.notify.email, d.notify.url].filter(Boolean).join(", ") + c.dim(` on ${(d.notify.events ?? []).join(", ") || "nothing"}`)
|
|
5846
|
+
? [d.notify.email, d.notify.url, d.notify.hidden ? `a webhook ${c.dim(`(${HIDDEN_NOTE})`)}` : null].filter(Boolean).join(", ") + c.dim(` on ${(d.notify.events ?? []).join(", ") || "nothing"}`)
|
|
5741
5847
|
: c.dim("nobody is told anything");
|
|
5742
5848
|
console.log(`\n ${c.bold("account defaults")} ${c.dim("every workspace here inherits these")}\n`);
|
|
5743
5849
|
console.log(` timezone ${d.timezone ?? c.dim("unset — schedules read UTC")}`);
|
|
@@ -5803,6 +5909,10 @@ async function telemetryCmd(url, args, flags) {
|
|
|
5803
5909
|
console.log(`\n ${c.dim("runs are not sent anywhere — foldrun account telemetry set https://<collector>/v1/traces --header authorization=\${OTEL_TOKEN}")}\n`);
|
|
5804
5910
|
return 0;
|
|
5805
5911
|
}
|
|
5912
|
+
if (t.hidden) {
|
|
5913
|
+
console.log(`\n ${c.bold("telemetry")} set ${c.dim(`— ${HIDDEN_NOTE}`)}\n`);
|
|
5914
|
+
return 0;
|
|
5915
|
+
}
|
|
5806
5916
|
console.log(`\n ${c.bold("telemetry")} ${t.endpoint}`);
|
|
5807
5917
|
for (const [k, v] of Object.entries(t.headers ?? {})) console.log(` ${c.dim(k)} ${v}`);
|
|
5808
5918
|
console.log();
|
|
@@ -5911,6 +6021,9 @@ async function mergedEntry(url, flags, key, args, workspace, view, how) {
|
|
|
5911
6021
|
/** A setting's value as one short line. */
|
|
5912
6022
|
function shortValue(v) {
|
|
5913
6023
|
if (v === null || v === undefined) return null;
|
|
6024
|
+
// The account's notify:/telemetry: to a key limited to some workspaces:
|
|
6025
|
+
// set, and where it goes is not shown (30 Oct 2026).
|
|
6026
|
+
if (v && typeof v === "object" && v.hidden === true) return `set ${c.dim(`(${HIDDEN_NOTE})`)}`;
|
|
5914
6027
|
return typeof v === "object" ? JSON.stringify(v).replace(/"([a-z_]+)":/g, "$1: ").replace(/,/g, ", ") : String(v);
|
|
5915
6028
|
}
|
|
5916
6029
|
|
|
@@ -11437,12 +11550,12 @@ async function secretOfKind(kind, flags) {
|
|
|
11437
11550
|
};
|
|
11438
11551
|
switch (kind) {
|
|
11439
11552
|
case "file":
|
|
11440
|
-
return { body: { file: read(flags.file, "--file <path> — the file the secret holds") }, local: (k, n, b, s) => k.setFileSecret("default", n, b.file, s) };
|
|
11553
|
+
return { body: { file: read(flags.file, "--file <path> — the file the secret holds") }, local: (k, n, b, s, l) => k.setFileSecret("default", n, b.file, s, l) };
|
|
11441
11554
|
case "ssh": {
|
|
11442
11555
|
if (typeof flags.host !== "string" || typeof flags.user !== "string") throw new Error("--kind ssh needs --host <host> --user <user> (--port, and --key-file <path> or a password, prompted)");
|
|
11443
11556
|
const port = flags.port !== undefined ? Number(flags.port) : undefined;
|
|
11444
11557
|
const auth = typeof flags["key-file"] === "string" ? { private_key: read(flags["key-file"], "--key-file <path>") } : { password: typeof flags.value === "string" ? flags.value : await promptHidden(" password: ") };
|
|
11445
|
-
return { body: { ssh: { host: flags.host, user: flags.user, ...(port ? { port } : {}), ...auth } }, local: (k, n, b, s) => k.setSshSecret("default", n, b.ssh, s) };
|
|
11558
|
+
return { body: { ssh: { host: flags.host, user: flags.user, ...(port ? { port } : {}), ...auth } }, local: (k, n, b, s, l) => k.setSshSecret("default", n, b.ssh, s, l) };
|
|
11446
11559
|
}
|
|
11447
11560
|
case "api": {
|
|
11448
11561
|
const lines = [].concat(flags.header ?? []);
|
|
@@ -11459,13 +11572,13 @@ async function secretOfKind(kind, flags) {
|
|
|
11459
11572
|
}),
|
|
11460
11573
|
);
|
|
11461
11574
|
const base = typeof flags["base-url"] === "string" ? { base_url: flags["base-url"] } : {};
|
|
11462
|
-
return { body: { api: { ...base, headers, ...basic } }, local: (k, n, b, s) => k.setApiSecret("default", n, b.api, s) };
|
|
11575
|
+
return { body: { api: { ...base, headers, ...basic } }, local: (k, n, b, s, l) => k.setApiSecret("default", n, b.api, s, l) };
|
|
11463
11576
|
}
|
|
11464
11577
|
case "identity": {
|
|
11465
11578
|
// A keyless cloud identity: only the audience; the platform signs the
|
|
11466
11579
|
// tokens (`foldrun identity` prints what the cloud must trust).
|
|
11467
11580
|
if (typeof flags.audience !== "string" || !flags.audience.trim()) throw new Error("--kind identity needs --audience <value your cloud's trust expects in aud>");
|
|
11468
|
-
return { body: { identity: { audience: flags.audience } }, local: (k, n, b, s) => k.setIdentitySecret("default", n, b.identity, s) };
|
|
11581
|
+
return { body: { identity: { audience: flags.audience } }, local: (k, n, b, s, l) => k.setIdentitySecret("default", n, b.identity, s, l) };
|
|
11469
11582
|
}
|
|
11470
11583
|
case "client-cert": {
|
|
11471
11584
|
// A client certificate for mutual TLS. Bind it to the exact hosts it is
|
|
@@ -11475,7 +11588,7 @@ async function secretOfKind(kind, flags) {
|
|
|
11475
11588
|
const key = read(flags["key-file"], "--key-file <key.pem> — its private key");
|
|
11476
11589
|
const passphrase = typeof flags.passphrase === "string" ? flags.passphrase : undefined;
|
|
11477
11590
|
const client_cert = { cert, key, ...(passphrase ? { passphrase } : {}), ...(flags.export === true ? { export: true } : {}) };
|
|
11478
|
-
return { body: { client_cert }, local: (k, n, b, s) => k.setClientCertSecret("default", n, b.client_cert, s) };
|
|
11591
|
+
return { body: { client_cert }, local: (k, n, b, s, l) => k.setClientCertSecret("default", n, b.client_cert, s, l) };
|
|
11479
11592
|
}
|
|
11480
11593
|
case "service-account": {
|
|
11481
11594
|
let j;
|
|
@@ -11488,14 +11601,14 @@ async function secretOfKind(kind, flags) {
|
|
|
11488
11601
|
// --subject: the user it acts as (domain-wide delegation, granted by the
|
|
11489
11602
|
// provider's admin); without it the account acts as itself.
|
|
11490
11603
|
const sa = { token_url: j.token_uri ?? "https://oauth2.googleapis.com/token", issuer: j.client_email, private_key: j.private_key, scope: flags.scopes ?? "", ...(typeof flags.subject === "string" ? { subject: flags.subject } : {}) };
|
|
11491
|
-
return { body: { service_account: sa }, local: (k, n, b, s) => k.setServiceAccountSecret("default", n, b.service_account, s) };
|
|
11604
|
+
return { body: { service_account: sa }, local: (k, n, b, s, l) => k.setServiceAccountSecret("default", n, b.service_account, s, l) };
|
|
11492
11605
|
}
|
|
11493
11606
|
case "m2m": {
|
|
11494
11607
|
if (typeof flags["token-url"] !== "string") throw new Error("--kind m2m needs --token-url, --client-id (and the client secret, prompted or --client-secret)");
|
|
11495
11608
|
const client_id = flags["client-id"] ?? (await promptVisible(" client_id: "));
|
|
11496
11609
|
const client_secret = flags["client-secret"] ?? (await promptHidden(" client_secret: "));
|
|
11497
11610
|
const oauth2 = { token_url: flags["token-url"], client_id, client_secret, grant_type: "client_credentials", ...(flags.scopes ? { extra: { scope: flags.scopes } } : {}) };
|
|
11498
|
-
return { body: { oauth2 }, local: (k, n, b, s) => k.setOAuth2Secret("default", n, b.oauth2, s) };
|
|
11611
|
+
return { body: { oauth2 }, local: (k, n, b, s, l) => k.setOAuth2Secret("default", n, b.oauth2, s, l) };
|
|
11499
11612
|
}
|
|
11500
11613
|
default:
|
|
11501
11614
|
throw new Error(`unknown --kind "${kind}" — file, ssh, api, service-account, m2m, client-cert or identity (a plain value needs no --kind; --oauth2 a refresh token; \`foldrun connect\` a browser sign-in)`);
|
|
@@ -11603,7 +11716,8 @@ async function apiVersionCmd(positional, flags) {
|
|
|
11603
11716
|
console.log(`\n ${c.bold("API version")} ${v.effective} ${c.dim(v.pinned ? `pinned (current is ${v.current})` : "current — not pinned")}`);
|
|
11604
11717
|
console.log(` ${c.dim(`served: ${(v.supported ?? []).join(", ") || "—"} · each for ${v.supportMonths ?? "?"} months after the next · this CLI sends ${API_VERSION}`)}`);
|
|
11605
11718
|
if (l.perCredential) console.log(` ${c.bold("rate limits")} ${c.dim(`${l.plan} · per key ${l.perCredential.read} reads / ${l.perCredential.write} writes, per account ${l.perAccount?.read} / ${l.perAccount?.write} — every ${l.windowSeconds}s`)}`);
|
|
11606
|
-
|
|
11719
|
+
if (facts.usageHidden) console.log(` ${c.bold("your use")} ${c.dim("shown only to a member or key with every workspace")}`);
|
|
11720
|
+
else apiUsageLines(facts.usage);
|
|
11607
11721
|
console.log(`\n ${c.dim("foldrun api version pin YYYY-MM-DD · unpin")}\n`);
|
|
11608
11722
|
return 0;
|
|
11609
11723
|
}
|