foldrun 9.0.2 → 10.0.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/docs/api.md +32 -23
- package/docs/notifications.md +8 -0
- package/docs/security.md +15 -4
- package/docs/storage-and-sharing.md +15 -0
- package/docs/team-and-access.md +1 -1
- package/package.json +2 -2
- package/src/commands.mjs +3 -1
package/docs/api.md
CHANGED
|
@@ -66,8 +66,8 @@ 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 |
|
|
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
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
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 |
|
|
@@ -76,7 +76,7 @@ api workspaces/$WS/flows/publish/run -X POST # start a flow
|
|
|
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` |
|
|
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.
|
|
@@ -205,10 +214,10 @@ paying for the steps around it.
|
|
|
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
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` |
|
|
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 |
|
|
@@ -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
|
|
|
@@ -294,7 +303,7 @@ URLs mean nothing in a run pod ever holds the bucket credential.
|
|
|
294
303
|
| Route | Methods | |
|
|
295
304
|
|---|---|---|
|
|
296
305
|
| `/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 |
|
|
306
|
+
| `/s/<token>` | GET, HEAD | the file itself, no credential, streamed; HEAD reads only its length. `429` past 120 a minute from one caller or 1,200 a minute for one link |
|
|
298
307
|
|
|
299
308
|
From the terminal: `foldrun storage share <path>`, `shares`, `unshare <token>`.
|
|
300
309
|
|
|
@@ -324,7 +333,7 @@ its header and requires a URL it can GET for itself.
|
|
|
324
333
|
|
|
325
334
|
| Route | Methods | |
|
|
326
335
|
|---|---|---|
|
|
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` |
|
|
336
|
+
| `/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. 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). PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set` |
|
|
328
337
|
|
|
329
338
|
`PUT` takes `name` plus exactly one shape: `value` (a string), `file` (a PEM,
|
|
330
339
|
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;
|
|
@@ -346,7 +355,7 @@ Reads return which secrets exist, never their values.
|
|
|
346
355
|
| `/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
356
|
| `/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
357
|
| `/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 |
|
|
358
|
+
| `/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 |
|
|
350
359
|
| `/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's as the wallet's are — since API version `2026-10-26` nothing else; earlier pins see `providerCostUsd` and `marginUsd` as `null` |
|
|
351
360
|
| `/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
361
|
| `/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 |
|
|
@@ -359,7 +368,7 @@ Reads return which secrets exist, never their values.
|
|
|
359
368
|
| `/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
369
|
| `/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 encrypted object), `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
370
|
| `/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
|
|
371
|
+
| `/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`; 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
372
|
| `/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
373
|
| `/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
374
|
| `/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 |
|
|
@@ -367,7 +376,7 @@ Reads return which secrets exist, never their values.
|
|
|
367
376
|
| `/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 |
|
|
368
377
|
| `/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
378
|
| `/api/schedule` | GET, POST | GET: every scheduled flow with `valid` (the cron parses) and `upcoming` (the next three fires). POST: tick the scheduler now — install-wide, so `workspace:manage`; returns `{ ok, fired }` |
|
|
370
|
-
| `/api/library/<kind>?path=` | GET, POST, PUT, DELETE | account-level shared documents (`name`, `content`, `path`, `template`) |
|
|
379
|
+
| `/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
380
|
| `/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
381
|
|
|
373
382
|
## Roles
|
|
@@ -378,7 +387,7 @@ least role that may take that action. Reads are open to every role.
|
|
|
378
387
|
| role | may |
|
|
379
388
|
|---|---|
|
|
380
389
|
| `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 |
|
|
390
|
+
| `editor` | + edit files, upload, deploy (to a workspace that exists), push; run, stop, re-run, approve and promote runs; test tools |
|
|
382
391
|
| `admin` | + create and delete workspaces; write secrets and connect credentials; mint keys; invite, re-role and remove editors and viewers |
|
|
383
392
|
| `owner` | + billing; make and unmake admins; transfer the account |
|
|
384
393
|
|
|
@@ -397,11 +406,11 @@ person: a key names an account, never a who.
|
|
|
397
406
|
|
|
398
407
|
| Route | Methods | |
|
|
399
408
|
|---|---|---|
|
|
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 |
|
|
409
|
+
| `/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
410
|
| `/api/billing/checkout` | POST | a Stripe session (`usd`) |
|
|
402
411
|
| `/api/billing/confirm?session_id=` | GET | settle one |
|
|
403
412
|
| `/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 |
|
|
413
|
+
| `/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
414
|
| `/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
415
|
| `/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
416
|
| `/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` |
|
|
@@ -437,15 +446,15 @@ X-Foldrun-Cli: 0.6.0 # the CLI released with this version (absent
|
|
|
437
446
|
| `/api/auth/session` | GET | who am I |
|
|
438
447
|
| `/api/auth/sessions` | GET, DELETE | list; revoke one (`id`) or the rest (`others`) |
|
|
439
448
|
| `/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
|
|
449
|
+
| `/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 sends no mail moves at once (`pending: false`) |
|
|
441
450
|
| `/api/auth/name` | POST | `firstName`, `lastName` — optional halves, null clears one; shown by email when empty |
|
|
442
451
|
| `/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 |
|
|
443
452
|
| `/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 |
|
|
453
|
+
| `/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
454
|
| `/api/auth/verify/resend` | POST | send the confirmation again, to the signed-in person, 3 an hour |
|
|
446
455
|
| `/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
456
|
| `/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 |
|
|
457
|
+
| `/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
458
|
| `/api/auth/mfa/disable` | POST | `password` and `code` — a session alone is not enough to remove the second factor |
|
|
450
459
|
| `/api/auth/timezone` | POST | `timezone` — what a cron expression means |
|
|
451
460
|
|
|
@@ -476,20 +485,20 @@ signed-in person, never by a key — mints an ordinary API key at their role.
|
|
|
476
485
|
| Route | Methods | |
|
|
477
486
|
|---|---|---|
|
|
478
487
|
| `/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 |
|
|
488
|
+
| `/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
489
|
| `/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
490
|
| `/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
491
|
| `/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 |
|
|
492
|
+
| `/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
493
|
| `/api/oauth/connections` | GET | each oauth2 secret's grant: saved client, `status` (ok, expiring, expired, failed, no-client), days left, last error |
|
|
485
494
|
|
|
486
495
|
## Triggers
|
|
487
496
|
|
|
488
497
|
| Route | Methods | |
|
|
489
498
|
|---|---|---|
|
|
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` |
|
|
499
|
+
| `/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
500
|
| `/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 token is derived from the run id, and the URL is printed in the waiting step's trace. `409` when the run is not waiting on an event |
|
|
501
|
+
| `/api/events/<tenant>/<ws>/<id>?token=` | POST | release a run parked on `wait: event`; the body becomes the step's event payload. The token is derived from the run id, and the URL is printed in the waiting step's trace. `409` when the run is not waiting on an event. Wrong tokens are limited per caller as a hook's are |
|
|
493
502
|
| `/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
503
|
| `/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
504
|
| `/api/workspaces/<ws>/hooks/<flow>/rotate` | POST | new token, old URLs stop working |
|
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
|
|
package/docs/security.md
CHANGED
|
@@ -169,6 +169,13 @@ Signing in, in particular:
|
|
|
169
169
|
- signing out ends the session on the server, not just in the browser;
|
|
170
170
|
- a two-step code works once; replacing a second factor means turning it
|
|
171
171
|
off first, which needs the password and a code;
|
|
172
|
+
- ten wrong two-step codes in a row pause codes from the app for up to a
|
|
173
|
+
day and mail the person — a backup code still signs in, and the pause
|
|
174
|
+
lifts by itself;
|
|
175
|
+
- changing your login address only mails the new address a link, and the
|
|
176
|
+
move happens when that link is clicked; asking answers the same whether
|
|
177
|
+
or not the address already has a login, so it cannot be used to find out
|
|
178
|
+
who has an account;
|
|
172
179
|
- the sign-in forms refuse a request from another site, and `?next=` only
|
|
173
180
|
ever leads to a page on the same site;
|
|
174
181
|
- `foldrun login` asks you to type the code your terminal shows — a link
|
|
@@ -176,12 +183,16 @@ Signing in, in particular:
|
|
|
176
183
|
as you;
|
|
177
184
|
- before the first sign-up, a self-hosted install's setup token guards key
|
|
178
185
|
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
|
|
186
|
+
- only the account's owner can set, rebind or remove the account's
|
|
187
|
+
`RESEND_API_KEY` and `EMAIL_FROM`, because that sender carries everyone's
|
|
188
|
+
reset links — whether through the secrets API or an OAuth connect;
|
|
189
|
+
- a key rotated by a caller that is no person (a key known only by its
|
|
190
|
+
label) acts as nobody, never as the rotated key's owner;
|
|
181
191
|
- a member or key limited to some workspaces cannot change what every
|
|
182
192
|
workspace shares — the library, the account's AGENTS.md defaults, its
|
|
183
|
-
model provider, its OAuth apps — nor people who work
|
|
184
|
-
workspaces
|
|
193
|
+
model provider, its OAuth apps, the API version pin — nor people who work
|
|
194
|
+
outside its workspaces, and does not read the other workspaces' provider
|
|
195
|
+
blocks or charges, nor the account's billing details.
|
|
185
196
|
|
|
186
197
|
Frontmatter is YAML only: a file opened with `---js` (which some parsers
|
|
187
198
|
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
|
|
@@ -66,6 +76,11 @@ 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
|
+
- Deleting a workspace revokes its links and deletes its stored files.
|
|
80
|
+
Renaming one moves both: its links keep working, under the new name.
|
|
81
|
+
- A link answers at most 120 requests a minute to one caller (where a trusted
|
|
82
|
+
proxy names the caller) and 1,200 a minute in all, then `429` with
|
|
83
|
+
`Retry-After`. The file is streamed, never read whole into memory.
|
|
69
84
|
|
|
70
85
|
Files written under **`storage/public/`** get a link automatically after the
|
|
71
86
|
run — for the agent that needs a URL for what it just produced.
|
package/docs/team-and-access.md
CHANGED
|
@@ -10,7 +10,7 @@ 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 |
|
|
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
14
|
| **admin** | + create and delete workspaces; 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
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "10.0.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
|
@@ -5316,7 +5316,9 @@ async function storageCmd(positional, flags, layout) {
|
|
|
5316
5316
|
}
|
|
5317
5317
|
try {
|
|
5318
5318
|
const sha = crypto.createHash("sha256").update(bytes).digest("hex");
|
|
5319
|
-
|
|
5319
|
+
// The length too: the platform checks the limits on it and signs it
|
|
5320
|
+
// into the URL, so the bucket takes exactly these bytes (30 Oct 2026).
|
|
5321
|
+
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
5322
|
// A platform older than presigned uploads answers 404 here: it
|
|
5321
5323
|
// takes the bytes itself, the way one with no bucket does.
|
|
5322
5324
|
if (!ask.ok && ask.status !== 404) throw new HttpError(await said(ask), ask.status, {});
|