foldrun 26.3.4 → 26.3.5

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/mcp.md CHANGED
@@ -35,8 +35,8 @@ you choose:
35
35
 
36
36
  - **what it may do** — read only (inbox, runs, flows, files), or read and act
37
37
  (also start and stop runs, approve gates, answer and message agents, and
38
- create workspaces and write or delete their files);
39
- - **which workspaces** — every one you may open, or the ones you tick.
38
+ create projects and write or delete their files);
39
+ - **which projects** — every one you may open, or the ones you tick.
40
40
 
41
41
  **Connect** sends you back to claude.ai, connected; **Deny** sends it a no.
42
42
  It is the same in the Claude apps on a phone, which share claude.ai's
@@ -82,7 +82,7 @@ address and the same lines.
82
82
 
83
83
  Every app connected over OAuth is listed in Settings → API keys → **Connected
84
84
  AI apps**: the app, where its answers went, whose approval, what access and
85
- which workspaces, when it was connected and last used. **Disconnect** ends it —
85
+ which projects, when it was connected and last used. **Disconnect** ends it —
86
86
  every token it holds stops at once — and the person can connect it again. You
87
87
  see your own; an admin sees everyone's and may disconnect any.
88
88
 
@@ -93,7 +93,7 @@ foldrun mcp disconnect <id> # asks first; --yes on a pipe
93
93
 
94
94
  What a connection may do is decided at every call, not only when it was
95
95
  approved: it acts as the person who approved it, at the lower of the role
96
- they chose then and the role they hold now, in the workspaces both allow. A
96
+ they chose then and the role they hold now, in the projects both allow. A
97
97
  person who leaves the account, or is made a viewer, takes their apps with
98
98
  them. The access token lasts an hour and opens `/api/mcp` only — sent to any
99
99
  other route it is refused. Refresh tokens rotate on every use, and one used
@@ -101,11 +101,11 @@ twice disconnects the app: someone else has a copy. **Machine clients.** A progr
101
101
  nightly job, a CI step or another service, can sign in with client
102
102
  credentials. An admin registers it in Settings → API keys → Connected AI apps
103
103
  (**Add a machine client**), or with `foldrun mcp clients add <name>`, choosing
104
- its role, its workspaces, and whether it may act or only read. It gets a
104
+ its role, its projects, and whether it may act or only read. It gets a
105
105
  client id and a secret, shown once, or it registers public keys and signs
106
106
  assertions (`private_key_jwt`). It asks the token endpoint with
107
107
  `grant_type=client_credentials` and gets an access token for an hour, with no
108
- refresh token: it simply asks again. It acts within the role and workspaces of
108
+ refresh token: it simply asks again. It acts within the role and projects of
109
109
  the admin who registered it, and stops if that admin loses them. It is listed
110
110
  with the connected apps, and disconnecting it ends it at once: its next token
111
111
  request is refused with `invalid_client`.
@@ -127,15 +127,15 @@ and that automatic disconnect are in the audit log (`mcp.connected`,
127
127
 
128
128
  | tool | does | route |
129
129
  |---|---|---|
130
- | `whoami` | the account, role and workspaces this key acts for | `GET /api/me` |
131
- | `list_workspaces` | the workspaces it may open | `GET /api/workspaces` |
130
+ | `whoami` | the account, role and projects this key acts for | `GET /api/me` |
131
+ | `list_workspaces` | the projects it may open | `GET /api/workspaces` |
132
132
  | `inbox` | what waits on you: approvals, questions, issues, proposed fixes, your failed runs (`bucket`, `kind`, `workspace`) | `GET /api/me/inbox` |
133
133
  | `list_approvals` | every gate waiting on a person, and every question an agent is asking | `GET /api/approvals` |
134
- | `list_flows` | a workspace's flows | `GET …/flows` |
135
- | `list_agents` | a workspace's agents: what each is for and when it last ran | `GET …/agents` |
134
+ | `list_flows` | a project's flows | `GET …/flows` |
135
+ | `list_agents` | a project's agents: what each is for and when it last ran | `GET …/agents` |
136
136
  | `list_runs` | recent runs, with outcome, summary and failure (`limit` up to 100, default 20; `flow` keeps that flow's among the newest 500) | `GET …/runs` |
137
137
  | `get_run` | one run in full | `GET …/runs/<id>` |
138
- | `read_file` | one file of a workspace's source (with its `sha256`), or the tree | `GET …/source` |
138
+ | `read_file` | one file of a project's source (with its `sha256`), or the tree | `GET …/source` |
139
139
  | `check_workspace` | what `foldrun check` says about a workspace: findings with rule ids (`security: true` for the security rules alone) | `GET …/check` |
140
140
  | `run_flow` | start a flow (`task`, `test: true` for a [test run](runs#test-runs), `context` for a turn of a [conversation](runs#conversations), `inputs` for [files](runs#inputs)) | `POST …/flows/<flow>/run` |
141
141
  | `run_agent` | run one agent on a task of your own, in its own sandbox, no flow needed (`task`, `test: true` for a [test run](runs#test-runs), `context` for a turn of a [conversation](runs#conversations), `inputs` for [files](runs#inputs)); answers a run id at once — read it with `get_run` | `POST …/agents/<agent>/run` |
@@ -143,7 +143,7 @@ and that automatic disconnect are in the audit log (`mcp.connected`,
143
143
  | `answer_question` | answer an agent's question mid-step | `POST …/runs/<id>/answer` |
144
144
  | `message_run` | say something to a running agent | `POST …/runs/<id>/message` |
145
145
  | `stop_run` | stop a run | `POST …/runs/<id>/stop` |
146
- | `create_workspace` | a new, blank workspace — an `AGENTS.md` and nothing else; refused when the name is taken | `POST /api/workspaces` |
146
+ | `create_workspace` | a new, blank project — an `AGENTS.md` and nothing else; refused when the name is taken | `POST /api/workspaces` |
147
147
  | `write_file` | create or replace one file — an agent, a flow, knowledge, a skill, `AGENTS.md` (`message` for the revision, `if_match` below) | `PUT …/source` |
148
148
  | `delete_file` | delete one file or folder | `DELETE …/source` |
149
149
 
@@ -161,7 +161,7 @@ build an automation, not only drive one: `create_workspace`, then
161
161
  `test: true`.
162
162
 
163
163
  - **A file written is live at once.** The next run reads it; there is no
164
- separate deploy. Each write is a revision in the workspace's
164
+ separate deploy. Each write is a revision in the project's
165
165
  [History](deploying#history-and-rollback), so a mistake is undone from there.
166
166
  - **It is checked as a deploy checks it.** A file with an error (a flow
167
167
  naming an agent that is not there, frontmatter YAML cannot read) is
@@ -179,10 +179,10 @@ folder and `foldrun deploy` it ([CLI](cli)); both reach the same files.
179
179
 
180
180
  Nothing a key could not. Each tool is a call to the route in the table, made
181
181
  with the same key — so a viewer's key cannot start, approve or stop; a key
182
- scoped to some workspaces sees and touches only those; an
182
+ scoped to some projects sees and touches only those; an
183
183
  [A2A key](a2a#a2a-keys) is refused (it opens `/a2a` and nothing else); and
184
184
  every check, limit and refusal is the route's own. A tool whose route refused
185
- answers `isError: true` with the route's words: `HTTP 403: this workspace is
185
+ answers `isError: true` with the route's words: `HTTP 403: this project is
186
186
  not one you were given access to`.
187
187
 
188
188
  `inbox` is a person's: a key minted by a person (every key from Settings, and
package/docs/network.md CHANGED
@@ -81,9 +81,9 @@ A site is a domain or `*.domain` — no scheme, no path, no port; every port
81
81
  of the host is covered. `*.example.com` covers `api.example.com`,
82
82
  `a.b.example.com` and `example.com` itself. Quote a wildcard in YAML.
83
83
 
84
- It is read on the agent, in the workspace's `AGENTS.md` and in the account's
84
+ It is read on the agent, in the project's `AGENTS.md` and in the account's
85
85
  `AGENTS.md`. The level and `defaults` are nearest-wins — the agent's, else the
86
- workspace's, else the account's. The `allow` lists add up across all three,
86
+ project's, else the account's. The `allow` lists add up across all three,
87
87
  so a site every agent needs is written once, in the account's `AGENTS.md`.
88
88
 
89
89
  `foldrun check` and every deploy refuse a value they cannot read — a level
@@ -229,14 +229,14 @@ say which applies to an agent.
229
229
 
230
230
  The list is refused when any one of three says so:
231
231
 
232
- - `network_enforce: true` in the account's `AGENTS.md` — every workspace;
233
- - `network_enforce: true` in a workspace's `AGENTS.md` — that workspace;
232
+ - `network_enforce: true` in the account's `AGENTS.md` — every project;
233
+ - `network_enforce: true` in a project's `AGENTS.md` — that project;
234
234
  - `FOLDRUN_NETWORK_ENFORCE=1` on the install's worker — every account.
235
235
 
236
- Each only switches it on. A workspace cannot turn off what its account
236
+ Each only switches it on. A project cannot turn off what its account
237
237
  turned on, and nothing in an account turns off the install's. Settings →
238
- Policies → Guardrail, on the account's and a workspace's Settings, has the switch, and so does
239
- `foldrun account set network_enforce on` / `foldrun workspace set
238
+ Policies → Guardrail, on the account's and a project's Settings, has the switch, and so does
239
+ `foldrun account set network_enforce on` / `foldrun project set
240
240
  network_enforce on --to <workspace>`.
241
241
 
242
242
  Until one of them says so, the proxy only **reports**: a site off the list
@@ -394,7 +394,7 @@ each call there through the egress proxy and gets back what the call wrote:
394
394
  does in the step — clicks, fills, frames, `js=` and `eval` (which run in
395
395
  the page, as always), screenshots, PDFs, video, HAR, downloads (they come
396
396
  back to the path the call names), uploads (the file is sent from the
397
- workspace), `session=` (kept as the browser's storage state in
397
+ project), `session=` (kept as the browser's storage state in
398
398
  `outputs/.browser/<name>/`, as on the account's browser pod), saved logins
399
399
  (`state:` and `state_key:`, read from and written to `state/browser/`),
400
400
  aria numbers, `mode=diff` and `mode=crawl`. The live view streams as before.
@@ -406,7 +406,7 @@ each call there through the egress proxy and gets back what the call wrote:
406
406
  - **What stays in the step**, exactly as before, saying so on the call: a
407
407
  `live:` session, engines other than Chromium and Chrome (Firefox, WebKit,
408
408
  Lightpanda, Obscura), `extensions:`, `proxy=`, a vendor's browser, a page
409
- on the sandbox's own machine or a private address, and a workspace whose
409
+ on the sandbox's own machine or a private address, and a project whose
410
410
  copy of the `web` tool was edited (the service runs foldrun's own program,
411
411
  never an edited one). A call the service could not start runs in the step;
412
412
  a call that started there and was cut off is **not** run again — it may
@@ -24,7 +24,7 @@ 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
27
+ `${NAME}` is filled from the vault, the project's first and then the
28
28
  account's, as for an agent. A secret [bound to sites](secrets#bound-to-sites)
29
29
  is filled only when the URL's host is one of them — bind `SLACK_WEBHOOK_URL`
30
30
  to `hooks.slack.com` and it goes there and nowhere else; named in a URL to
@@ -95,7 +95,7 @@ which is the class of failure that otherwise reaches nobody:
95
95
  |---|---|
96
96
  | `quarantined` | a flow's `disable_after:` tripped and it has stopped firing |
97
97
  | `sla` | a run has passed its flow's `sla:` and is still going |
98
- | `budget` | a workspace has spent 80%, then 95%, of its `budget:` for the window — today, this week or this month |
98
+ | `budget` | a project has spent 80%, then 95%, of its `budget:` for the window — today, this week or this month |
99
99
  | `security` | the daily rescan found a security finding that was not there before — see [Checks](checks#online-checks-and-the-daily-rescan) |
100
100
  | `room` | a run has waited an hour for room to start (`FOLDRUN_ROOM_ALERT_MIN`) — it keeps its place and starts when there is room; see [waiting for room](budgets-and-billing#waiting-for-room) |
101
101
 
@@ -112,7 +112,7 @@ of them, leave `failed` out of the list.
112
112
 
113
113
  ## Thresholds: `alerts:`
114
114
 
115
- A failure is told when it happens. A workspace can also ask to hear when a
115
+ A failure is told when it happens. A project can also ask to hear when a
116
116
  pattern crosses a line, with `alerts:` in its `AGENTS.md` (or the account's):
117
117
 
118
118
  ```yaml
@@ -127,9 +127,9 @@ alerts:
127
127
  new_host: true # an agent reached a site it never reached before
128
128
  ```
129
129
 
130
- A workspace's `alerts:` replaces the account's whole: once it has its own,
130
+ A project's `alerts:` replaces the account's whole: once it has its own,
131
131
  the account's thresholds no longer apply there, and `alerts: {}` means none
132
- for that workspace (`new_host: false` turns off one the account has on).
132
+ for that project (`new_host: false` turns off one the account has on).
133
133
  Without an `alerts:` of its own it takes the account's.
134
134
 
135
135
  Each comes to `notify:` as event `alert` — like the three above it follows
@@ -176,19 +176,19 @@ has checked, through a mail domain nobody has verified — and on 2026-09-06
176
176
  every run email had been going to a bin for weeks, with silence as the only
177
177
  symptom. Silence looks exactly like nothing having gone wrong.
178
178
 
179
- Workspace settings has a button that sends one real message to the saved
179
+ Project settings has a button that sends one real message to the saved
180
180
  destination and reports what came back, including the provider's own words
181
181
  on a failure. Those words are the value: "domain not verified" and "you can
182
182
  only send to your own address" send you to two different pages, and a status
183
183
  code sends you to neither. `POST /api/workspaces/<ws>/notify/test` is the
184
- same thing. A workspace gets 10 test sends an hour; past that the button
184
+ same thing. A project gets 10 test sends an hour; past that the button
185
185
  says to wait.
186
186
 
187
187
  ## Where it is set, and the rule that bites
188
188
 
189
- `notify:` lives in the account's `AGENTS.md` and every workspace inherits it.
190
- A workspace may declare its own — and when it does, its block **replaces**
191
- the account's whole, it does not merge. A workspace that wants the account's
189
+ `notify:` lives in the account's `AGENTS.md` and every project inherits it.
190
+ A project may declare its own — and when it does, its block **replaces**
191
+ the account's whole, it does not merge. A project that wants the account's
192
192
  destination and events simply says nothing.
193
193
 
194
194
  ## What arrives
@@ -254,7 +254,7 @@ The URL is read from `notify:` at each attempt, so fixing a typo in it is
254
254
  picked up by the next retry. The body is kept as first sent, so a retry is
255
255
  the same bytes.
256
256
 
257
- **Where to see it.** The workspace's Triggers page ends with *Outbound
257
+ **Where to see it.** The project's Triggers page ends with *Outbound
258
258
  webhook deliveries*: every delivery, its status, its attempts, and a
259
259
  **Redeliver** button. From a terminal, `foldrun webhooks deliveries --to
260
260
  <ws>` (`--failed` for the ones that gave up) and `foldrun webhooks
@@ -266,7 +266,7 @@ reject links as `[redacted]`: they decide without a login, and every role
266
266
  can read the log. The receiver still gets them, on a redelivery too.
267
267
 
268
268
  **An endpoint that stays down is switched off.** When every attempt to a
269
- workspace's URL has failed for **3 days running** (the operator's
269
+ project's URL has failed for **3 days running** (the operator's
270
270
  `FOLDRUN_WEBHOOK_DISABLE_DAYS`), the next delivery to give up after all
271
271
  six attempts switches it off, and the platform emails the account's owner
272
272
  once. A first attempt that fails does not switch it off on its own, however
@@ -372,15 +372,15 @@ sending, so it holds for every mail, from every part of the platform.
372
372
  | `invites` | an invitation to join an account | no |
373
373
  | `billing` | a payment failed, and the grace before runs stop | no |
374
374
  | `account` | a notification webhook switched off after days of failures; a close request; an API route the account still calls that is being switched off | no |
375
- | `run-alerts` | a workspace's `notify:` email: failed, completed, blocked, quarantined, `sla`, `budget` | yes — per workspace |
376
- | `approvals` | a run waiting for you, with approve and reject links | yes — per workspace |
375
+ | `run-alerts` | a project's `notify:` email: failed, completed, blocked, quarantined, `sla`, `budget` | yes — per project |
376
+ | `approvals` | a run waiting for you, with approve and reject links | yes — per project |
377
377
  | `low-balance` | credits below the warning level | yes |
378
378
  | `product-updates` | what changed in foldrun | yes |
379
379
 
380
380
  The four that cannot be turned off are how you get back into the account
381
381
  and how you hear that something you rely on has stopped; the page shows
382
382
  them, switched on and locked, with that reason. `run-alerts` and
383
- `approvals` can be off for one workspace and on for the rest (`foldrun
383
+ `approvals` can be off for one project and on for the rest (`foldrun
384
384
  notifications set run-alerts off --to seo-desk`).
385
385
 
386
386
  **Unsubscribing from a mail.** Every mail in an optional category carries a
@@ -390,7 +390,7 @@ List-Unsubscribe=One-Click`, so the mail client's own Unsubscribe button
390
390
  works, plus a "Stop …" link at the bottom that opens a page asking first
391
391
  (opening a link never unsubscribes — inbox scanners open links). The token
392
392
  is signed by the install, names one address, one category and — for run
393
- alerts and approvals — one workspace, and works for 180 days. No login is
393
+ alerts and approvals — one project, and works for 180 days. No login is
394
394
  needed, and the address need not belong to anyone with one: a `notify:
395
395
  email` that reaches a shared inbox can be unsubscribed by whoever reads it.
396
396
  A choice made this way shows on that person's Profile → Notifications, and
package/docs/oauth.md CHANGED
@@ -55,7 +55,7 @@ authorization server (Keycloak) and against recorded provider answers.
55
55
  | Resource indicators | RFC 8707 | Supported | Tokens are bound to /api/mcp. |
56
56
  | Issuer in the authorization response | RFC 9207 | Supported | Every answer carries `iss`. |
57
57
  | Revocation endpoint | RFC 7009 | Supported | `POST /api/mcp/oauth/revoke`: an app ends its own connection. |
58
- | Client credentials for machine clients | RFC 6749 §4.4 | Supported | An admin registers a machine client (Settings, or `foldrun mcp clients add`) with a role, workspaces and access; no refresh token; disconnecting it makes it `invalid_client`. |
58
+ | Client credentials for machine clients | RFC 6749 §4.4 | Supported | An admin registers a machine client (Settings, or `foldrun mcp clients add`) with a role, projects and access; no refresh token; disconnecting it makes it `invalid_client`. |
59
59
  | Signed client assertion (private_key_jwt) | RFC 7523 §2.2 | Supported | Apps that register `jwks` or `jwks_uri` sign in with assertions; each `jti` is used once. |
60
60
 
61
61
  ## Refused on purpose
package/docs/providers.md CHANGED
@@ -6,8 +6,8 @@ The simplest way to bring a key: **Settings → Models**, or
6
6
  `foldrun account model set <provider> --key <api key>`, or
7
7
  `PUT /api/account/model`. Pick a name from the table below (or `custom`
8
8
  with a base URL and a format), paste an **API key**, and every step in
9
- every workspace runs on it. No `provider:` block is needed; one written in
10
- an agent, a workspace or the account's AGENTS.md still wins over it.
9
+ every project runs on it. No `provider:` block is needed; one written in
10
+ an agent, a project or the account's AGENTS.md still wins over it.
11
11
 
12
12
  The key is stored in the account's vault, encrypted under the account's own
13
13
  key, as `FOLDRUN_MODEL_PROVIDER`, `FOLDRUN_MODEL_API_KEY` and, for a custom
@@ -48,7 +48,7 @@ billed in credits at **foldrun's price list**
48
48
  shows; `ifVersion` on the PUT) makes either refused (409) when someone
49
49
  chose since you read it, as the Settings page does.
50
50
  - **The order** a step's model is found in is unchanged but for one rung: a
51
- `provider:` block in the agent, the workspace or the account's AGENTS.md
51
+ `provider:` block in the agent, the project or the account's AGENTS.md
52
52
  first; then foldrun's models, when chosen; then the account's own key.
53
53
  - **Which model a tier runs** is the platform's map for that provider
54
54
  (`model: fast | default | max`), shown on the page and by
@@ -325,7 +325,7 @@ and the platform used to find that out the way you would: a desk failing at
325
325
  five in the morning.
326
326
 
327
327
  Once a day, every provider block this account's files actually use — the
328
- account's, each workspace's, each agent's — is asked one minimal question:
328
+ account's, each project's, each agent's — is asked one minimal question:
329
329
  a single request, one token of output, at the endpoint a run would use, with
330
330
  the key a run would send. It costs a fraction of a cent, and a year of it
331
331
  costs less than one ordinary run. Blocks sharing an endpoint and a key are
@@ -383,7 +383,7 @@ supply is configured
383
383
  ```
384
384
 
385
385
  Reset times are told in the step's own timezone, resolved by the usual
386
- cascade (agent → flow → workspace → account → `FOLDRUN_TIMEZONE` → UTC), so
386
+ cascade (agent → flow → project → account → `FOLDRUN_TIMEZONE` → UTC), so
387
387
  a run scheduled in Sydney is not told when its quota returns in UTC.
388
388
 
389
389
  Three things the line is careful about:
@@ -408,7 +408,7 @@ implying a wait nobody promised.
408
408
  **Where the step can go next is part of the sentence.** Every refusal line
409
409
  ends with one of three states: `trying the second supply`, `the second
410
410
  supply refused it too`, or `no second supply is configured`. The last is a
411
- deliberate arrangement, not a gap — a workspace with one provider and no
411
+ deliberate arrangement, not a gap — a project with one provider and no
412
412
  fallback is a normal thing to run — and it is said out loud so a step never
413
413
  ends in silence over it.
414
414
 
package/docs/runs.md CHANGED
@@ -19,7 +19,7 @@ Each run holds its steps in group order. A step carries:
19
19
  | `turns`, `systemPromptChars`, `stopReason` | model turns, summed across attempts; the system prompt's length in characters (it rides on every turn); why the last turn ended. With the events' `bytes`, these say where a step's input tokens went. From 18 Oct 2026 |
20
20
  | `promptLayers` | the system prompt's layers, stable ones first: `name` (`persona`, `agents.md`, `skills`, `knowledge`, `rules`, … then `memory`, `state`, `clock`), `chars`, `hash` (12 hex characters of its SHA-256) and `stable: false` on the ones that change between runs. Two steps of one agent compared layer by layer say why the [prompt cache](budgets-and-billing#prompt-caching) missed; the run page and `foldrun report` do the comparison. From 20 Oct 2026 |
21
21
  | `costUsd`, `tokens`, `computeSecs`, `startupSecs` | what it cost and how long the sandbox lived — **summed across its attempts**. `tokens` is `{ input, output, cacheRead, cacheWrite }`: `input` is all input, and `cacheRead` and `cacheWrite` the part of it the [prompt cache](budgets-and-billing#prompt-caching) served and stored. Steps recorded before 18 Oct 2026 have only `input` and `output` |
22
- | `startup` | where the step's first seconds went: when each start-up phase ended, in seconds since the step started — `services` (the account's search/browser pods up), `room` (room on the cluster to start — see [Budgets and billing](budgets-and-billing)), `applied` (sandbox created), `ready`, `files` (workspace copied in), `go` (step released), `shim`, `system` (system packages restored), `driver`, `imports`, `tools` (runtime and tools built) and `model` (the model's first text or tool call). `services` can end after `ready` and `files`: the search and browser pods boot beside the step pod, and `go` waits for them. Only the phases the step went through; `null` for a step that ran in-process, absent before 17 Oct 2026. The last attempt's |
22
+ | `startup` | where the step's first seconds went: when each start-up phase ended, in seconds since the step started — `services` (the account's search/browser pods up), `room` (room on the cluster to start — see [Budgets and billing](budgets-and-billing)), `applied` (sandbox created), `ready`, `files` (project copied in), `go` (step released), `shim`, `system` (system packages restored), `driver`, `imports`, `tools` (runtime and tools built) and `model` (the model's first text or tool call). `services` can end after `ready` and `files`: the search and browser pods boot beside the step pod, and `go` waits for them. Only the phases the step went through; `null` for a step that ran in-process, absent before 17 Oct 2026. The last attempt's |
23
23
  | `image` | which runner image the step's sandbox ran (isolated runs on a cluster): `variant` `full` or `slim`, `why`, and `pod: true` when a browsing step ran slim and browsed through the account's browser pod ([slim steps and a lost pod](tools#slim-steps-and-a-lost-pod)) |
24
24
  | `browserPod` | on a step that browsed through the pod from slim: `reconnects` (tries), `reconnected` (how many got through: the call went on after it) and `closedAgain` (how many reached the pod only for the call to drop again at once, when any did); when the pod was lost, `lost` (`cause` `lost` or `needs-full`, and `detail`) and `writes` (what the step had written by then, worded); then `fallback: "browser pod lost; re-ran on full"` when it had only read and ran again on the full image, or `failure` — `browser pod died after the step had written <what>` — when it had written and was not re-run |
25
25
  | `tries` | one row per attempt, oldest first (and a `status: "lost"` row, `image: "slim"`, before the full re-run when the browser pod was lost under a slim step that had only read — see [tools](tools#slim-steps-and-a-lost-pod)): `n` (the try, numbered in the order they ran), `attempt` (the step's attempt it belongs to, only when that is not `n` — the full re-run after a lost slim try 1 is `n: 2, attempt: 1`), `status`, `costUsd`, `tokens`, `turns`, `computeSecs`, `startedAt`, `finishedAt`, the attempt's `image` and its `browserPod` line when it had one, and the attempt's last `error` when it failed. A `retry: 2` step that failed twice and then passed has three rows, and its `costUsd` is all three — the run's spend, the flow's `budget:` and the bill read the step's figure, so the figure is the total. A retry is handed what is left of the budget after the failed attempt spent, and nothing left means no retry, said on the record |
@@ -55,7 +55,7 @@ reach the model's first word; hover it for each phase's share. When the
55
55
  account's search or browser pod was still booting as the step pod came up,
56
56
  `services` reads as its own lane (`services 8.00s alongside the pod`), the
57
57
  pod's phases keep their own shares, and `go` says how long it was held for
58
- the services (`go +0.10s (held 4.00s for services)`). The workspace's
58
+ the services (`go +0.10s (held 4.00s for services)`). The project's
59
59
  **Observe** page and `foldrun observe --to` roll the same breakdown up over
60
60
  every step.
61
61
 
@@ -93,7 +93,7 @@ desk's **last 24 runs** as a strip of cells beside how many of them
93
93
  completed and what went wrong (`20/22 · 2 failed`), runs today and the
94
94
  credits charged this week. Every row and every cell opens its run.
95
95
 
96
- Money on the overviews — Home, the desks list, a workspace's flows and
96
+ Money on the overviews — Home, the desks list, a project's flows and
97
97
  agents, Observe, the runs list and a run's own page — is **credits charged**:
98
98
  the ledger's line for the run, one credit to a cent. A run the ledger has not
99
99
  settled yet shows its list price, marked estimated (`~` in the runs list,
@@ -129,7 +129,7 @@ What each says:
129
129
  `resources:`, or a plan that allows more. *The step ran out of memory.
130
130
  Memory limit: 4 GiB; last recorded peak: 3.9 GiB* — a larger `size:` or
131
131
  `resources: { memory: … }`. The same for cores, disk and `timeout:`. A
132
- step bigger than its flow's or workspace's `compute:` names that
132
+ step bigger than its flow's or project's `compute:` names that
133
133
  `compute:`; only a limit a plan sets mentions a plan. A machine running
134
134
  short and the cluster evicting the step is said as that — not as the
135
135
  step over its own limit.
@@ -172,15 +172,15 @@ Every step keeps, beside its events:
172
172
  content, line by line — then anything shaped like a key, and any private
173
173
  key block. The input is what the agent asked for; a [hook](hooks) that
174
174
  rewrote it before it ran is in the trace beside it. The content is kept
175
- beside the run, not in it, counts toward the workspace's storage, and goes
175
+ beside the run, not in it, counts toward the project's storage, and goes
176
176
  when the run is deleted or ages out.
177
177
 
178
- And the run itself says **which files it ran** — the workspace's latest
178
+ And the run itself says **which files it ran** — the project's latest
179
179
  revision when a worker first picked it up ("ran on abc1234"; a deploy's is
180
180
  its commit) — and **how long it queued** before that. A step that runs after
181
181
  an approval, or after a deploy mid-run, may run newer files than that.
182
182
 
183
- A workspace that should keep no content writes `capture: metadata` in its
183
+ A project that should keep no content writes `capture: metadata` in its
184
184
  `AGENTS.md` (or the account's): model calls, tool names, sizes and timings
185
185
  are still recorded, inputs and outputs are not.
186
186
 
@@ -215,9 +215,9 @@ telemetry:
215
215
 
216
216
  In the account's `AGENTS.md` (Settings → Policies → Observability → *Send runs to your
217
217
  tracing*, or `foldrun account telemetry set <url> --header
218
- authorization='${OTEL_TOKEN}'`), or a workspace's, which replaces the
218
+ authorization='${OTEL_TOKEN}'`), or a project's, which replaces the
219
219
  account's whole. Every run that finishes is sent as one trace. Resource
220
- attributes name the account, workspace, flow and run. Ids come from the
220
+ attributes name the account, project, flow and run. Ids come from the
221
221
  run's, so a run sent twice is one trace. Test runs are not sent.
222
222
 
223
223
  The spans follow the [OpenTelemetry GenAI semantic
@@ -351,8 +351,8 @@ the revision its new run ran ("regressed since abc1234"). Besides **Snooze
351
351
  known flake (`snooze` with `times` on the API, `--times` in the CLI).
352
352
 
353
353
  **Doctor** on an issue opens the [run doctor](assistant#the-run-doctor) on
354
- its newest run, in the workspace that run is in, wherever the card is shown
355
- (Home, a workspace's home, the Issues page): the assistant says why and
354
+ its newest run, in the project that run is in, wherever the card is shown
355
+ (Home, a project's home, the Issues page): the assistant says why and
356
356
  proposes the fix as files to save. Nothing changes until you save it; then
357
357
  resolve the issue, or rerun and let it show "fine since". A missed schedule
358
358
  has no run, so it has no Doctor. From a terminal: `foldrun issues doctor <id>`.
@@ -369,10 +369,10 @@ failures, BLOCKED and BAD (marked "auto"); one going wrong after that opens a
369
369
  new episode. Unset (`stay-open`) a person resolves them. Platform causes and
370
370
  missed schedules never close on their own.
371
371
 
372
- The **Issues** page lists them (Open, Snoozed, Resolved, All; a workspace's
372
+ The **Issues** page lists them (Open, Snoozed, Resolved, All; a project's
373
373
  own from its home), Home lists the open ones under Needs attention, and
374
374
  `foldrun issues` and `GET /api/issues` are the same list. A platform issue
375
- belongs to the account: closing it needs access to every workspace.
375
+ belongs to the account: closing it needs access to every project.
376
376
 
377
377
  Each agent also has an **Activity** page: every step it has ever run, across
378
378
  flows and direct runs, with that step's own headline. It is where "how has
@@ -381,7 +381,7 @@ this agent been going" is answered without opening runs one at a time.
381
381
  ## Your inbox
382
382
 
383
383
  **Inbox**, top right and under View in the account's sidebar, is what waits
384
- on *you*, across every workspace you may see, in one list: gates to approve,
384
+ on *you*, across every project you may see, in one list: gates to approve,
385
385
  questions agents are asking, open [issues](#issues), [proposed
386
386
  fixes](evals#proposed-fixes) to review, and your own runs that went wrong.
387
387
 
@@ -389,9 +389,9 @@ Three tabs that never mix:
389
389
 
390
390
  | tab | what is in it |
391
391
  |---|---|
392
- | **For me** | assigned to you: you are named in the flow's `approvers:`, you own the flow or agent (`owner:`, down to the workspace's and the account's), or you asked for the proposal |
392
+ | **For me** | assigned to you: you are named in the flow's `approvers:`, you own the flow or agent (`owner:`, down to the project's and the account's), or you asked for the proposal |
393
393
  | **Started by me** | runs you started: one that failed or ended BLOCKED or BAD in the last week, a gate on one (someone else must decide it — your own approval is refused), a question one is asking |
394
- | **Team** | everything else waiting in your workspaces, for whoever picks it up — a gate anyone may decide, an issue nobody owns |
394
+ | **Team** | everything else waiting in your projects, for whoever picks it up — a gate anyone may decide, an issue nobody owns |
395
395
 
396
396
  Nothing is kept in it: each item is read from where it lives and leaves on
397
397
  its own when it is done there — the gate decided, the issue resolved, the
@@ -403,7 +403,7 @@ so an issue that happens again after you set it aside comes back. The count
403
403
  on the top bar is what is unread in For me and Started by me.
404
404
 
405
405
  `foldrun inbox` prints the same (`--team`, `--all`, `--kind approval`); a key
406
- reads the inbox of the person who minted it, within the key's own workspaces.
406
+ reads the inbox of the person who minted it, within the key's own projects.
407
407
  The API is `GET /api/me/inbox`.
408
408
 
409
409
  ## Gates
@@ -429,7 +429,7 @@ but skip the third one" is an instruction the publisher reads.
429
429
 
430
430
  **Who may answer.** A flow's `approvers:` names the addresses that may decide
431
431
  its gates, or `admins` for anyone at admin or above; unset, anyone who can
432
- run the workspace can answer. On top of that, and whatever the list says,
432
+ run the project can answer. On top of that, and whatever the list says,
433
433
  **nobody approves a run they started themselves** — a gate exists so a second
434
434
  person looks. Rejecting your own run is always allowed. An API key carries a
435
435
  role but no address, so a key is not caught by the self-approval rule and
@@ -466,7 +466,7 @@ What the platform does on a test run, in the order a step meets it:
466
466
  | the egress proxy | any `POST`, `PUT`, `PATCH` or `DELETE` to a host that is not a model provider or a read-only service is **refused** with `403` and a JSON body `{ "test_mode": true, "would_have": { method, host, path, to, body } }`. A Resend `POST /emails` is instead **redirected**: the recipients become `delivered@resend.dev` (Resend's sink), the subject is prefixed `[TEST] `, and the call goes through — so a desk still gets a real message id. Reads (`GET`, `HEAD`, `OPTIONS`) pass. A host with no granted secret is refused as always |
467
467
  | the sandbox | secrets whose name says they can send — `RESEND_API_KEY`, `TWILIO_*`, `GETREACH_API_KEY`, `GITHUB_TOKEN`, `MONDAY_API_TOKEN`, `OI_CRM_API_KEY`, `CLOUDFLARE_*`, `LINKEDIN_*`, `MEDIUM_COOKIES`, `TIKTOK_*` — are **withheld**: the env var reads `TEST_MODE_WITHHELD`, so a script that never checked fails at the provider with an auth error rather than sending. A step granting a script tool marked `outward: true` gets no real secret at all; one granting a tool marked `test_mode: allow` gets them all. The sandbox also has `FOLDRUN_TEST_MODE=1` and `FOLDRUN_RUN_TEST=1`, for scripts that branch on it. The http tools still go through the proxy, where the table above applies |
468
468
  | the browser | the step is handed no account [browser pod](tools#where-the-browser-runs): the tool launches Chromium inside the run pod, which the run namespace's policy denies the internet, so a `web action=browse` call fails closed rather than fetching the world through a pod the policy does not select |
469
- | the write-back | `state/` and `storage/` go into the sandbox as they are; what the step wrote there comes out under `runs/<id>/test-writes/state/…` and `…/storage/…`, and the workspace's copies are untouched. Each later step of the run gets those writes laid over its copy, times kept, so a flow that hands work on through `storage/` is tested as it runs live — the step's log says how many files it sees. Nothing is harvested to the file store and nothing under `storage/public/` is published |
469
+ | the write-back | `state/` and `storage/` go into the sandbox as they are; what the step wrote there comes out under `runs/<id>/test-writes/state/…` and `…/storage/…`, and the project's copies are untouched. Each later step of the run gets those writes laid over its copy, times kept, so a flow that hands work on through `storage/` is tested as it runs live — the step's log says how many files it sees. Nothing is harvested to the file store and nothing under `storage/public/` is published |
470
470
  | the record | `test: true`; the summary opens with `[test]`; a **TEST** badge beside the status in the runs list and on the run page; every refusal, redirect, diversion and withheld secret is an event carrying an `effect`, and the run page's **Test run** panel lists them — "would have written state/sends.md, +3 lines" |
471
471
  | the rest | gates still park, and the approve page says it is a test run; notifications go out only for `failed`; a `trigger: flow` chained on a test run starts as a test run |
472
472
 
@@ -497,7 +497,7 @@ morning when one broken thing failed seventy runs. A call naming no filter is
497
497
  refused rather than treated as everything, `dryRun: true` shows what would be
498
498
  touched, and each run is its own outcome so one that cannot be stopped does
499
499
  not abort the rest. On the runs pages, tick runs and choose **Stop** or
500
- **Rerun**: the bar makes this call, once per workspace in the selection.
500
+ **Rerun**: the bar makes this call, once per project in the selection.
501
501
 
502
502
  **Re-run from a group** (`from: N`) starts a new run at group N with the
503
503
  earlier groups recorded as skipped, not invented — the step reads what earlier
@@ -517,7 +517,7 @@ waited out, a throttled trigger, a flow switched off after a bad week, an
517
517
  already had its most runs waiting (*too many runs waiting* —
518
518
  [how many runs may wait](budgets-and-billing#how-many-runs-may-wait)).
519
519
 
520
- The Triggers page on each workspace records all of it: one row per flow
520
+ The Triggers page on each project records all of it: one row per flow
521
521
  saying how often its trigger fired, how often that became a run, and what
522
522
  the difference was, with the key in the flow file that decided each one. Its
523
523
  last section is the delivery log, which answers the separate and earlier
@@ -553,7 +553,7 @@ The API takes the same field: `context` on `POST …/agents/<agent>/run` and
553
553
  `POST …/flows/<flow>/run` (not with `from`), and on MCP's `run_agent` and
554
554
  `run_flow`. Over [A2A](a2a), a task's `contextId` is its context.
555
555
 
556
- **What counts as an earlier turn:** a run of the same workspace and context,
556
+ **What counts as an earlier turn:** a run of the same project and context,
557
557
  completed or failed, that had finished before this run was started. A test
558
558
  run reads only test runs, and a real run only real ones. The cutoff is fixed
559
559
  when the run is made, so a retry, a park at a gate or a rescue reads the same
@@ -572,7 +572,7 @@ that do not fit are left out. The step's trail says what it was given:
572
572
  `conversation order-42: given 3 earlier runs (4,210 characters)`.
573
573
 
574
574
  **Who shares a context:** runs started through the API, the dashboard, the
575
- CLI or MCP share the workspace's contexts, so anyone who can start runs there
575
+ CLI or MCP share the project's contexts, so anyone who can start runs there
576
576
  can continue one — and could read those runs anyway. A context is a way to
577
577
  group runs, not a lock. Each outside caller over A2A has its own: two A2A keys
578
578
  that send the same `contextId` never see each other's turns, and an A2A
@@ -584,7 +584,7 @@ list them.
584
584
 
585
585
  ## Inputs
586
586
 
587
- A run may be handed **files**: storage paths, as the workspace's storage lists
587
+ A run may be handed **files**: storage paths, as the project's storage lists
588
588
  them. The step the task reaches finds them at `inputs/` in its working
589
589
  directory, under the same paths (`inputs/reports/q4.pdf`), and is told which
590
590
  they are. An agent reads them with its Read tool; images and PDFs are shown to
@@ -662,7 +662,7 @@ What follows from it:
662
662
 
663
663
  - **Held alone.** Each customer is held to its own limits, checked before the
664
664
  account's own: by default **30 run starts a minute** and **10 runs open at
665
- once** (queued, running or waiting at a gate, across every workspace). One
665
+ once** (queued, running or waiting at a gate, across every project). One
666
666
  customer past a limit is refused while your other customers carry on: too
667
667
  many starts is `429` with `Retry-After` and code `customer_rate`; too many
668
668
  open is `429` with code `customer_open_runs` — one must finish first. Open
@@ -675,7 +675,7 @@ What follows from it:
675
675
  so calls at once cannot pass it together. A run past it is refused at its
676
676
  next model call. None is set by default. `GET /api/customers/usage?days=7`
677
677
  and `foldrun customers usage` show what each customer was charged.
678
- - **Blocked.** An admin with every workspace can block a customer
678
+ - **Blocked.** An admin with every project can block a customer
679
679
  (Settings → API keys → Customers, `foldrun customers block <id>`, or
680
680
  `PUT /api/customers/<id>/block`). Its runs are refused at start (`403`,
681
681
  code `customer_blocked`), and a run of it already going stops at its next
@@ -704,7 +704,7 @@ code `customer_required`).
704
704
 
705
705
  Every step records what it cost. A flow's `budget:` is checked between
706
706
  groups: the group that crosses it is the last that runs, and the run fails
707
- saying so. The workspace's and the account's `budget:` over time sit above
707
+ saying so. The project's and the account's `budget:` over time sit above
708
708
  that. See [Budgets and billing](budgets-and-billing).
709
709
 
710
710
  ## How long a run is kept
@@ -752,7 +752,7 @@ live is read whole; a finished run's reply and trace are opened by id.
752
752
  The list pages by position, not by number: `GET …/runs` answers `next`, a
753
753
  cursor for the runs older than the last one it sent, and `before=<next>`
754
754
  asks for that page, so runs that start meanwhile shift nothing. One cursor
755
- pages every workspace, which is how `foldrun runs` pages the account:
755
+ pages every project, which is how `foldrun runs` pages the account:
756
756
  `--limit` sets the page, `--page 3` or `--before <cursor>` picks one (the
757
757
  command prints the next one's cursor), and `--all` reads every run that
758
758
  matches.
@@ -14,7 +14,7 @@ frontmatter.
14
14
  | `webhook` | an HTTP POST reaches the flow's hook URL | the request body |
15
15
  | `email` | a message arrives at the flow's inbox URL | from, to, subject, text |
16
16
  | `flow` | the flow in `after:` settles the way `on:` says | that run's id, status, summary, result |
17
- | `storage` | a file lands under `path:` in this workspace's storage | the paths and who wrote them |
17
+ | `storage` | a file lands under `path:` in this project's storage | the paths and who wrote them |
18
18
  | `watch` | the content at `url:` changes (polled every `every:`, default 15m) | the new content |
19
19
 
20
20
  A flow may not chain on itself. `watch` records its first sighting without