foldrun 26.3.3 → 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/secrets.md CHANGED
@@ -3,8 +3,8 @@
3
3
  A secret is a value an agent may use and must never see written down. It is
4
4
  stored in the platform's vault, named in an agent's `secrets:` list, and
5
5
  handed to that agent's scripts as an environment variable at run time. It is
6
- never written into the workspace, never printed into a prompt, and never in
7
- git — which is what makes a workspace safe to commit.
6
+ never written into the project, never printed into a prompt, and never in
7
+ git — which is what makes a project safe to commit.
8
8
 
9
9
 
10
10
  ## Setting one
@@ -38,7 +38,7 @@ Reads return which secrets exist, never their values.
38
38
  A **service account** is a key file that signs its own token request. It
39
39
  acts as itself, or — with **Act as** (`subject`) — as a user the provider
40
40
  lets it act for (RFC 7523's grant subject; for Google, domain-wide
41
- delegation, which a Workspace admin grants in their own console). Each
41
+ delegation, which a Project admin grants in their own console). Each
42
42
  subject gets its own token.
43
43
 
44
44
  An **`api`** connection is a base URL and the headers that go with it. For
@@ -62,20 +62,20 @@ tokens (RFC 8705), which foldrun does not do.
62
62
 
63
63
  ## Scopes
64
64
 
65
- A secret lives at the **account** or in one **workspace**. An agent looks in
66
- its workspace first, then the account; a workspace secret shadows an account
65
+ A secret lives at the **account** or in one **project**. An agent looks in
66
+ its project first, then the account; a project secret shadows an account
67
67
  one of the same name. The run trace says which scope each secret came from
68
- (`secret DATAFORSEO_LOGIN ← workspace scope`), so a workspace quietly falling
68
+ (`secret DATAFORSEO_LOGIN ← workspace scope`), so a project quietly falling
69
69
  back to a shared credential is visible rather than silent.
70
70
 
71
- Put a credential at the account when every workspace should use the same one
72
- — your model provider, your email sender. Put it in a workspace when it is
71
+ Put a credential at the account when every project should use the same one
72
+ — your model provider, your email sender. Put it in a project when it is
73
73
  that job's — a customer's Search Console, a CRM key.
74
74
 
75
- ### Limited to some workspaces
75
+ ### Limited to some projects
76
76
 
77
- An account secret is open to every workspace by default. To share one
78
- credential with a few workspaces but not the rest — the way GitHub limits an
77
+ An account secret is open to every project by default. To share one
78
+ credential with a few projects but not the rest — the way GitHub limits an
79
79
  organisation secret to selected repositories — limit it:
80
80
 
81
81
  ```sh
@@ -93,31 +93,31 @@ refused (409) when another admin changed it since — what Settings sends as
93
93
 
94
94
  In the dashboard it is **Workspaces: all / selected** on the secret's row in
95
95
  Settings → Secrets, and on the form that adds one; over the API,
96
- `PATCH /api/secrets { name, workspaces }` (`null` for every workspace, `[]`
96
+ `PATCH /api/secrets { name, workspaces }` (`null` for every project, `[]`
97
97
  for none), or `workspaces` on the `PUT` that stores the value. Given with the
98
98
  value, the two are saved in one write: the secret is never open to every
99
- workspace in between. "All" includes workspaces made later. Every other workspace finds the
99
+ project in between. "All" includes projects made later. Every other project finds the
100
100
  secret **not set**, exactly as if it had never been stored: a run reports it
101
101
  missing, a tool test and a `notify:` or `telemetry:` header leave
102
102
  `${NAME}` unfilled, the egress proxy has nothing to fill, an MCP server does
103
103
  not get it, a notification email it sends does not go out through the
104
104
  account's `RESEND_API_KEY` or `EMAIL_FROM` (the platform's sender is used, if
105
- there is one), and the workspace's secret list and the editor's completions
106
- leave it out. A workspace's own secret of the same name still works there.
105
+ there is one), and the project's secret list and the editor's completions
106
+ leave it out. A project's own secret of the same name still works there.
107
107
 
108
108
  A limit applies to runs that **start after it**. A run already going keeps
109
109
  what it was given when it started — values in its sandbox, and the ones the
110
110
  egress proxy fills for it — so stop a running one to cut it off at once.
111
111
 
112
- The names must be workspaces that exist. Renaming a workspace carries its
113
- place on every list; deleting one takes it off first, so a new workspace
112
+ The names must be projects that exist. Renaming a project carries its
113
+ place on every list; deleting one takes it off first, so a new project
114
114
  given the old name inherits nothing. If a secret limited to it cannot be read
115
115
  with the platform's keys, the rename or delete is refused and names it — set
116
116
  it again or delete it, then try again. Only an admin with access to every
117
- workspace sets the limit, and the account's `RESEND_API_KEY` and `EMAIL_FROM`
117
+ project sets the limit, and the account's `RESEND_API_KEY` and `EMAIL_FROM`
118
118
  stay the owner's, signed in (no key, not even `foldrun login`). The account's own uses of a secret — its model key in
119
119
  Settings → Models, and the mail the platform sends for the account (password
120
- resets, invites, billing) — are not a workspace's and are not limited. A new
120
+ resets, invites, billing) — are not a project's and are not limited. A new
121
121
  value or a new site binding keeps the limit. Limiting a secret seals the list
122
122
  with the value, like `sites` (see [How they are kept](#how-they-are-kept)),
123
123
  whatever form the secret was stored in before: a list changed on disk makes
@@ -148,7 +148,7 @@ call the same API the step did.
148
148
 
149
149
  A value with a line break in it — a PEM key, a service-account JSON — cannot
150
150
  travel as an environment variable. It arrives as a file instead: a
151
- private file in the step's copy of the workspace, with the variable holding
151
+ private file in the step's copy of the project, with the variable holding
152
152
  its path, and the run log names the secret that was handed over that way.
153
153
 
154
154
  ## Where the value actually is
@@ -428,7 +428,7 @@ The safest credential is none at all. A cloud that supports workload
428
428
  identity federation — AWS (`AssumeRoleWithWebIdentity`), Google Cloud
429
429
  (Workload Identity Federation), Microsoft Entra (federated credentials) —
430
430
  can trust **foldrun's signature** instead of a key you store: a step proves
431
- which account, workspace and agent it is, and the cloud gives it a
431
+ which account, project and agent it is, and the cloud gives it a
432
432
  short-lived credential of its own.
433
433
 
434
434
  1. In your cloud, trust this install as an OIDC provider: its issuer is
@@ -455,7 +455,7 @@ What it is and is not:
455
455
  stops or ends.
456
456
  - Stopping a step stops renewal; it cannot recall a token already issued,
457
457
  which expires within ten minutes on its own.
458
- - Within an account, a workspace or agent recreated under the same name
458
+ - Within an account, a project or agent recreated under the same name
459
459
  is the same subject: pin your trust policy to the account at least.
460
460
  - Who may run or edit an agent that names the identity may use it — as
461
461
  with every secret.
package/docs/security.md CHANGED
@@ -10,7 +10,7 @@ and cannot do, and why.
10
10
  Every step executes in its own sandbox, created for it and destroyed after
11
11
  it: a hardened container on a single box, a **gVisor** pod on a cluster.
12
12
  The sandbox holds a copy of the agent's folder and nothing else — not the
13
- platform's filesystem, not the vault, not another workspace. When the step
13
+ platform's filesystem, not the vault, not another project. When the step
14
14
  ends, its files copy back through a filter, and the sandbox is gone.
15
15
 
16
16
  Startup is under a second warm, so this is not the latency it sounds like;
@@ -39,7 +39,7 @@ internet and its own account's search and browser pods; nothing else. An
39
39
  agent that is `trusted` or `none` (the default for one that does not read
40
40
  the web) reaches the internet only through the egress proxy, which holds
41
41
  its list of sites per connection; where it is enforced
42
- (`network_enforce: true` in the account's or workspace's `AGENTS.md`, or
42
+ (`network_enforce: true` in the account's or project's `AGENTS.md`, or
43
43
  `FOLDRUN_NETWORK_ENFORCE=1` on the install) its pod has no other route, and no way to the
44
44
  account's browser or search pods. A step that browses is held the same way where the
45
45
  install sets `FOLDRUN_BROWSE_ENFORCE=1`: its browser runs inside that walled pod
@@ -50,7 +50,7 @@ the browser only: the step's other programs, and the calls the service does not
50
50
  serve, still reach sites directly.) The policy denies every private range (RFC1918) and the
51
51
  cloud metadata endpoint — the address that, on a cloud host, hands out the
52
52
  machine's own credentials. It cannot reach the platform's API, its
53
- database, its object store, or another account's pods. Workspace files
53
+ database, its object store, or another account's pods. Project files
54
54
  come and go through presigned URLs, so no bucket credential is ever in a
55
55
  pod. A [test run](runs#test-runs) is denied the internet and the browser
56
56
  pod as well, at the network, so an outward call from a script fails closed
@@ -71,9 +71,9 @@ about the platform.
71
71
  ## What the file tools allow
72
72
 
73
73
  An agent's built-in Read, Write, Edit, Glob and Grep are confined to its
74
- workspace: its own folder, the workspace's shared directories, and the
74
+ workspace: its own folder, the project's shared directories, and the
75
75
  account library read-only. A path outside — an invented `/tmp/…`, an
76
- absolute path, a directory a tool cloned outside the workspace — is refused
76
+ absolute path, a directory a tool cloned outside the project — is refused
77
77
  with a message naming the path the agent probably meant. Three more things
78
78
  stay off limits inside the workspace: the secrets file, the run journal,
79
79
  and the generated index of a knowledge bundle.
@@ -83,7 +83,7 @@ wasted turn; a prompt that names the exact path brings the count to zero.
83
83
 
84
84
  **A run does not change its own configuration or code.** What a step
85
85
  writes to `AGENTS.md`, `agents/`, `flows/`, `tools/`, `hooks/`, `skills/`,
86
- `evals/` or `scripts/` is not kept: the workspace keeps its own copy, and
86
+ `evals/` or `scripts/` is not kept: the project keeps its own copy, and
87
87
  the run page lists each such path under "Not kept". A prompt injection
88
88
  cannot widen what later runs may do. Data comes back as before — `state/`,
89
89
  `storage/`, `memory/`, `knowledge/`. The one exception is a step a person
@@ -95,7 +95,7 @@ on the trail as "kept with approval". That is how an approved fix lands.
95
95
 
96
96
  An agent names a secret in `secrets:`; the model never sees the value — it
97
97
  sees that a tool exists and calls it. Secrets are never written into a
98
- workspace, never in git, and reads of the vault return names, not values.
98
+ project, never in git, and reads of the vault return names, not values.
99
99
 
100
100
  On a cluster the value does not enter the sandbox either. The worker keeps
101
101
  it and the step sends its API and model requests through a per-step
@@ -123,7 +123,7 @@ when that step presents its token — and a lease nobody but the worker could
123
123
  have signed is refused.
124
124
 
125
125
  Backups are encrypted before they leave the server. The nightly archive —
126
- every workspace, run record and the database — and the server's key file
126
+ every project, run record and the database — and the server's key file
127
127
  are encrypted with age to a public key whose private half is not on the
128
128
  server, so a copy of the backup bucket opens nothing; the job refuses to run
129
129
  rather than ship anything unencrypted. See [Backups and restore](backups-and-restore).
@@ -183,7 +183,7 @@ a forwarded link cannot walk past `approvers:`. Only a digest of a used
183
183
  token is kept, and a key rotation kills every old link. Share links are 24 random
184
184
  bytes; every failed fetch is the same 404.
185
185
 
186
- Every write to a workspace is a revision with an author; every sign-in, key
186
+ Every write to a project is a revision with an author; every sign-in, key
187
187
  use and role change is in the audit log; every step's tool calls, script
188
188
  runs and refusals are in the run's events. A run can be reconstructed from
189
189
  its record.
@@ -191,7 +191,7 @@ its record.
191
191
  ## What our telemetry carries
192
192
 
193
193
  Your run's record — its prompts, replies, files, tool arguments and errors —
194
- is yours, in your workspace, and goes where you send it (`telemetry:` to your
194
+ is yours, in your project, and goes where you send it (`telemetry:` to your
195
195
  own OpenTelemetry collector, `notify:` to your webhook). The platform's own
196
196
  logs and metrics are a different thing: they go to our own operations store
197
197
  (in a bucket only it can read; the platform team reads it to see what happened
@@ -201,7 +201,7 @@ never carry your content.
201
201
  | Carries | Never carries |
202
202
  |---|---|
203
203
  | ids: account, member, API key (its id, never the key), request, run, job, task, lease, pod | prompts, replies, a step's output |
204
- | the names of your workspaces, flows, agents and evals | file names or contents, knowledge, memory |
204
+ | the names of your projects, flows, agents and evals | file names or contents, knowledge, memory |
205
205
  | counts, durations, bytes, dollars, HTTP status | tool or script arguments and results |
206
206
  | an error's class (`timeout`, `oom`, `disk_full`, `model_error`, `network_error`, `policy_denied`, `user_code_error`, `not_found`, `cancelled`, `platform_error`), its type, its errno or SQLSTATE, and where in **our** code it happened | an error's message or stack text, a model process's stderr, a query or its values |
207
207
  | a reason word from a fixed set (`paused`, `key_revoked`, `bad_credentials`) | URLs, email addresses, anything with a space in it |
@@ -346,10 +346,10 @@ Signing in, in particular:
346
346
  leaked laptop key cannot repoint the reset mail and take the account;
347
347
  - a key rotated by a caller that is no person (a key known only by its
348
348
  label) acts as nobody, never as the rotated key's owner;
349
- - a member or key limited to some workspaces cannot change what every
350
- workspace shares — the library, the account's AGENTS.md defaults, its
349
+ - a member or key limited to some projects cannot change what every
350
+ project shares — the library, the account's AGENTS.md defaults, its
351
351
  model provider, its OAuth apps, the API version pin — nor people who work
352
- outside its workspaces, and does not read the other workspaces' provider
352
+ outside its projects, and does not read the other projects' provider
353
353
  blocks or charges, nor the account's billing details.
354
354
 
355
355
  Frontmatter is YAML only: a file opened with `---js` (which some parsers
@@ -388,7 +388,7 @@ screen. `--json` is exact too: JSON writes control characters as escapes.
388
388
  is a write. Scope the credential to what the tool must do.
389
389
  - Bring-your-own-key credentials are yours; the platform stores them sealed
390
390
  and hands them to your steps, and never sees the bill.
391
- - The CLI on your machine runs steps as you, in your workspace, unless
391
+ - The CLI on your machine runs steps as you, in your project, unless
392
392
  `FOLDRUN_RUN_ISOLATION=container` is set. That is your laptop and your
393
393
  call. See [Running it yourself](self-hosting).
394
394
 
@@ -1,13 +1,13 @@
1
1
  # Running it yourself
2
2
 
3
- There are three places a workspace runs, and the same folder moves between
3
+ There are three places a project runs, and the same folder moves between
4
4
  them unchanged.
5
5
 
6
6
  | shape | for | what is yours |
7
7
  |---|---|---|
8
8
  | **your machine** | one person, no server — the foldrun CLI and runtime, free from npm | everything: the files, the runs, the model bill |
9
9
  | **your own server** | you or your organisation on one machine: the dashboard, schedules, sandboxes, gates, a vault and a team, with Docker Compose | everything, and the machine |
10
- | **the hosted platform** | a team that would rather not run anything | your workspaces and their records; we run the machines |
10
+ | **the hosted platform** | a team that would rather not run anything | your projects and their records; we run the machines |
11
11
 
12
12
  foldrun is **source-available** under the Functional Source License 1.1
13
13
  (FSL-1.1-ALv2): the format, the runner, the checks, the CLI, the engine and
@@ -182,7 +182,7 @@ cd my-desk && foldrun check && foldrun run publish
182
182
 
183
183
  Everything the format defines works here: agents, flows with groups and
184
184
  gates, tools in any language, skills, knowledge bundles, evals, `verify:`,
185
- `each:`, `budget:`. Runs are recorded under `.foldrun/` beside the workspace;
185
+ `each:`, `budget:`. Runs are recorded under `.foldrun/` beside the project;
186
186
  secrets set with `foldrun secrets set` are encrypted there under a key the
187
187
  CLI makes on first use.
188
188
 
@@ -190,10 +190,10 @@ What is different from the platform, and why:
190
190
 
191
191
  - **No schedules.** Nothing is running when your laptop is closed. `foldrun
192
192
  run` is the trigger; cron on your own machine works if you want one.
193
- - **No sandbox by default.** Steps run as your user, in your workspace. Set
193
+ - **No sandbox by default.** Steps run as your user, in your project. Set
194
194
  `FOLDRUN_RUN_ISOLATION=container` with Docker installed to get one hardened
195
195
  container per step, the same executor the platform's single-box shape uses.
196
- Without one, a step's file tools may not write the workspace's configuration
196
+ Without one, a step's file tools may not write the project's configuration
197
197
  or code (`AGENTS.md`, agents, flows, tools, skills, evals, scripts), but its
198
198
  shell is not confined: only a sandbox keeps those files out of a step's reach.
199
199
  - **Gates wait in the terminal.** A `!` step parks the run; `foldrun run`
@@ -217,10 +217,10 @@ Nothing about the folder changes. What the platform adds is the operating around
217
217
  ## Moving records into the database
218
218
 
219
219
  Runs, the trigger log and the storage file index used to be files on the data
220
- volume. With a database configured they move into Postgres, one workspace at a
220
+ volume. With a database configured they move into Postgres, one project at a
221
221
  time, while the other processes keep running.
222
222
 
223
- A row per workspace in `records_routing` says where its records are, and every
223
+ A row per project in `records_routing` says where its records are, and every
224
224
  process with a database reads the same rows:
225
225
 
226
226
  | State | Meaning |
@@ -229,13 +229,13 @@ process with a database reads the same rows:
229
229
  | `moving` | An import is making the rows match the files. A record call waits up to 5 s, then is refused as busy. |
230
230
  | `database` | The rows are the records, for good. There is no way back to files. |
231
231
 
232
- A workspace with no row follows `('*', '*')`, the install's default, which
232
+ A project with no row follows `('*', '*')`, the install's default, which
233
233
  stays `files` until a move has taken everything. `FOLDRUN_RECORDS=files` means
234
- only "this process never starts a move": a workspace another process moved is
234
+ only "this process never starts a move": a project another process moved is
235
235
  read and written as rows there too, and a process that cannot read the routing
236
236
  for 10 s refuses record calls rather than guess.
237
237
 
238
- A move copies the files into rows, holds the workspaces at `moving` until every
238
+ A move copies the files into rows, holds the projects at `moving` until every
239
239
  process seen in the last 30 s has acknowledged it, makes the rows exactly what
240
240
  the files say, flips them to `database`, and only then sets the files aside as
241
241
  `.imported-<date>`.
@@ -248,25 +248,25 @@ the files say, flips them to `database`, and only then sets the files aside as
248
248
  routing, so a move while one runs would hide what it reads.
249
249
  2. Remove `FOLDRUN_RECORDS=files`. A rolling restart is fine: the first process
250
250
  to boot in database mode moves everything. Pick a quiet moment — a run
251
- saving while its workspace is held can fail as busy.
252
- 3. Watch the ops log: `records.on_files` (workspaces still on files, with the
251
+ saving while its project is held can fail as busy.
252
+ 3. Watch the ops log: `records.on_files` (projects still on files, with the
253
253
  `records.import_failed` that says why; the next boot tries again),
254
254
  `records.move_abandoned` (`reason=not_acknowledged`: an old or stuck process
255
255
  did not answer within 60 s) and `records.stray_set_aside` (a record file
256
- found in a workspace already in the database; kept as `.stray-<date>`, never
256
+ found in a project already in the database; kept as `.stray-<date>`, never
257
257
  merged in).
258
258
 
259
259
  The timings are `FOLDRUN_RECORDS_ROUTING_BEAT_MS` (1000),
260
260
  `FOLDRUN_RECORDS_ROUTING_LEASE_MS` (10000), `FOLDRUN_RECORDS_MOVING_WAIT_MS`
261
261
  (5000), `FOLDRUN_RECORDS_ACK_WAIT_MS` (60000) and `FOLDRUN_RECORDS_SETTLE_MS`
262
- (120000, raise it for very large workspaces); keep them the same on every
262
+ (120000, raise it for very large projects); keep them the same on every
263
263
  process.
264
264
 
265
265
  ## Moving secrets into the database
266
266
 
267
- Each account's secrets, and each workspace's own, are a sealed `secrets.json`
267
+ Each account's secrets, and each project's own, are a sealed `secrets.json`
268
268
  on the data volume. With a database configured they can be rows in Postgres
269
- instead, one row per account or workspace (`vault_scopes`), holding the same
269
+ instead, one row per account or project (`vault_scopes`), holding the same
270
270
  sealed records: nothing in the database ever holds a value in the clear, and
271
271
  nothing below opens one except `verify --open`, in memory.
272
272
 
@@ -298,7 +298,7 @@ node --experimental-strip-types scripts/vault-fleet.ts export [--tenant a,b]
298
298
  file's lock. A row that exists is never replaced by a file. It is safe to
299
299
  repeat and to run while `secrets.store` is on.
300
300
  - `export` is the way back: it writes every row into its file as stored. A
301
- workspace row whose folder is gone is skipped and named; the folder is never
301
+ project row whose folder is gone is skipped and named; the folder is never
302
302
  brought back.
303
303
 
304
304
  **Moving, and then stopping the files:**
@@ -337,7 +337,7 @@ row is only ever read from the row while the store is on.
337
337
 
338
338
  ## Where the data is
339
339
 
340
- On your machine: in the folder. On the platform: your workspace's files and
340
+ On your machine: in the folder. On the platform: your project's files and
341
341
  every run's record, on our data volume and in the file store, readable
342
342
  through the dashboard and the API, exportable as a .zip (`foldrun export`). A deploy never
343
343
  touches what an agent learned or a run recorded. See [Storage and
package/docs/status.md CHANGED
@@ -25,7 +25,7 @@ that read the same record:
25
25
  | Scheduler | it has ticked in the last fifteen minutes | the samples themselves — they are written from inside the scheduler's tick, so a stale sample *is* a stopped scheduler |
26
26
  | Model providers | `api.anthropic.com` answers, and fewer than two step attempts in the last hour failed with a provider error (overloaded, rate limited, a 5xx; a refused credential only when two accounts saw one — one account's own expired key is that account's) | a reachability check, and the run records |
27
27
  | Email | `api.resend.com` answers | a reachability check; `unknown` on an install without a platform mail key |
28
- | Storage | the database answers and the workspace volume is writable | the same checks `healthz` makes |
28
+ | Storage | the database answers and the project volume is writable | the same checks `healthz` makes |
29
29
 
30
30
  Each is `operational`, `degraded`, `outage`, `maintenance` or `unknown`
31
31
  (not measured — not counted against uptime). An incident or maintenance
@@ -1,6 +1,6 @@
1
1
  # Storage and sharing
2
2
 
3
- Two kinds of file live in a workspace, and the dashboard shows them on two
3
+ Two kinds of file live in a project, and the dashboard shows them on two
4
4
  pages. **Files** is the markdown source — agents, flows, tools, knowledge —
5
5
  the thing you edit and deploy. **Storage** is bytes: what agents produce
6
6
  and what people upload — reports, CSVs, images, PDFs. This page is about the
@@ -9,7 +9,7 @@ second.
9
9
  ## Where it lives, from an agent's point of view
10
10
 
11
11
  An agent writes a deliverable to `workspace/storage/` (the older
12
- `../../storage/` is the same place) and it appears on the workspace's Storage page after the
12
+ `../../storage/` is the same place) and it appears on the project's Storage page after the
13
13
  step, kept and downloadable. Uploads dropped on that page land in the same
14
14
  directory and are there for the next run to read.
15
15
 
@@ -25,7 +25,7 @@ across runs is `state/`.
25
25
 
26
26
  ## Limits
27
27
 
28
- One object up to 512 MB; a workspace up to 5 GB, shown on the Storage page.
28
+ One object up to 512 MB; a project up to 5 GB, shown on the Storage page.
29
29
  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.
@@ -37,17 +37,17 @@ refuses a body of any other length. Recording the file afterwards measures
37
37
  the object the bucket holds; the record, the limit and the quota use that,
38
38
  never the length the client claimed, and an object over a limit is removed.
39
39
 
40
- Storage belongs to a workspace that exists: a name with no workspace is a
40
+ Storage belongs to a project that exists: a name with no project is a
41
41
  `404`, never a fresh, empty store.
42
42
 
43
43
  ## Under the hood
44
44
 
45
45
  Blobs are content-addressed and go to object storage (S3-compatible — R2, S3
46
46
  — or local disk on a small install); the index of what exists stays with the
47
- workspace. Uploading the same bytes under a second name costs nothing, and a
47
+ project. Uploading the same bytes under a second name costs nothing, and a
48
48
  rename moves no data. A run pod never holds the bucket credential: it reads
49
49
  and writes through presigned URLs, so a step that goes wrong cannot list or
50
- delete what other workspaces stored.
50
+ delete what other projects stored.
51
51
 
52
52
  ## Sharing a file
53
53
 
@@ -73,7 +73,7 @@ foldrun storage unshare <token|id> --to <ws>
73
73
  - The token is 24 random bytes and never derived from the path; every failed
74
74
  fetch is the same 404, so a guesser learns nothing.
75
75
  - Only `storage/`, `outputs/` and `files/` can be shared. An agent talked
76
- into sharing is confined to what the workspace produced and can never hand
76
+ into sharing is confined to what the project produced and can never hand
77
77
  out `memory/`, a prompt, or a credential.
78
78
  - Revoking is permanent; a re-share mints a new token.
79
79
  - Revoking takes effect at once: a link is served `Cache-Control: private,
@@ -81,7 +81,7 @@ foldrun storage unshare <token|id> --to <ws>
81
81
  - Only an admin, or the person who made a link, sees its token and can copy
82
82
  it. Everyone else sees that the file is shared, by whom and until when;
83
83
  an editor can still revoke it (by its id).
84
- - Deleting a workspace revokes its links and deletes its stored files.
84
+ - Deleting a project revokes its links and deletes its stored files.
85
85
  Renaming one moves both: its links keep working, under the new name.
86
86
  - A link answers at most 120 requests a minute to one caller (where a trusted
87
87
  proxy names the caller) and 1,200 a minute in all, then `429` with
@@ -97,17 +97,17 @@ works from inside.
97
97
  A share is a record the platform keeps, not a file in the workspace: minted
98
98
  from the dashboard or after a step, it lands in the platform's database,
99
99
  so every web and worker process sees the same links and a link survives a
100
- workspace being redeployed.
100
+ project being redeployed.
101
101
 
102
102
  ## The account view
103
103
 
104
- Storage at the account level lists every workspace as its own section, each
104
+ Storage at the account level lists every project as its own section, each
105
105
  closed until you open it, with each file's size, age and share state. It is a
106
- view: a run still sees only its own workspace's folder.
106
+ view: a run still sees only its own project's folder.
107
107
 
108
- You can upload any file, of any type, to any workspace from there. Use
109
- **Upload** in the toolbar and pick the workspace, use the **Upload** button on
110
- a workspace's section, or drop files onto that section. From a terminal,
108
+ You can upload any file, of any type, to any project from there. Use
109
+ **Upload** in the toolbar and pick the project, use the **Upload** button on
110
+ a project's section, or drop files onto that section. From a terminal,
111
111
  `foldrun storage put` does the same, and it takes folders whole:
112
112
 
113
113
  ```sh
@@ -9,9 +9,9 @@ whose supervisors cannot see what the agents did is not supervised.
9
9
 
10
10
  | role | may |
11
11
  |---|---|
12
- | **viewer** | read everything — workspaces, runs and their output, files, history, usage |
13
- | **editor** | + edit files, upload, deploy (to a workspace that exists — a deploy that makes one is an admin's), push; run, stop, re-run, approve and promote runs; test tools |
14
- | **admin** | + create and delete workspaces; delete a run from history; write secrets and connect credentials; mint keys; invite, re-role and remove editors and viewers |
12
+ | **viewer** | read everything — projects, runs and their output, files, history, usage |
13
+ | **editor** | + edit files, upload, deploy (to a project that exists — a deploy that makes one is an admin's), push; run, stop, re-run, approve and promote runs; test tools |
14
+ | **admin** | + create and delete projects; delete a run from history; write secrets and connect credentials; mint keys; invite, re-role and remove editors and viewers |
15
15
  | **owner** | + billing; make and unmake admins; transfer the account |
16
16
 
17
17
  There is exactly one owner: the account's creator until they transfer it.
@@ -23,15 +23,15 @@ promote peers is an owner with extra steps.
23
23
 
24
24
  A refused call answers `403` with the role that was needed.
25
25
 
26
- ### A workspace's policy is an admin's
26
+ ### A project's policy is an admin's
27
27
 
28
- The keys in a workspace's `AGENTS.md` that set policy for the whole
29
- workspace — `budget`, `compute`, `notify`, `network_enforce`, `telemetry`,
28
+ The keys in a project's `AGENTS.md` that set policy for the whole
29
+ project — `budget`, `compute`, `notify`, `network_enforce`, `telemetry`,
30
30
  `alerts`, `owner`, `judge` and `timezone` (also when written under a
31
31
  `governance:`, `guardrail:`, `observability:` or `evaluation:` block) — and a
32
32
  flow's `a2a:`, which decides whether outside agents may call it ([A2A](a2a)) — need
33
33
  the **admin** role to change, whichever way the file is written: the
34
- workspace's settings, a save in the editor (`PUT …/source`), `foldrun deploy`,
34
+ project's settings, a save in the editor (`PUT …/source`), `foldrun deploy`,
35
35
  an import, or a restore to an older point. An editor still edits the rest of
36
36
  `AGENTS.md` — its prose and every other key — and may deploy, import or
37
37
  restore anything that leaves those keys as they are; a change to one of them
@@ -41,23 +41,23 @@ it counts as a change too. A dry run (deploy, import, restore) is not
41
41
  refused.
42
42
 
43
43
  The account's own `AGENTS.md` is written only through the account's settings
44
- (`PATCH /api/account`), which needs an admin with access to every workspace.
44
+ (`PATCH /api/account`), which needs an admin with access to every project.
45
45
 
46
46
  ## Scoped members
47
47
 
48
- A member can be limited to some workspaces. The customer whose desk lives in
49
- one workspace sees that workspace's runs and files and nothing else; the
48
+ A member can be limited to some projects. The customer whose desk lives in
49
+ one project sees that project's runs and files and nothing else; the
50
50
  sidebar, Find, the runs list and the approvals banner all filter to their
51
51
  scope. Scope is set on the invite and changed per member later.
52
52
 
53
53
  Secrets and OAuth connections follow the scope too. A scoped member or key
54
- sees and changes only its own workspaces' secrets and connections: not
55
- another workspace's, and not the account-level ones, which belong to
56
- everyone's workspaces at once.
54
+ sees and changes only its own projects' secrets and connections: not
55
+ another project's, and not the account-level ones, which belong to
56
+ everyone's projects at once.
57
57
 
58
58
  ## Invites
59
59
 
60
- An invite carries a role, a workspace scope, and usually an email address it
60
+ An invite carries a role, a project scope, and usually an email address it
61
61
  is bound to — only that address can accept it. It is sent through the
62
62
  account's email connection, or returned as a link to pass on yourself; an
63
63
  invite with no address is a link for one person, whoever opens it first.
@@ -66,7 +66,7 @@ invite with no address is a link for one person, whoever opens it first.
66
66
  creates the member; a second person, or the same person again, is refused.
67
67
  It lasts seven days.
68
68
  - **Pending invites are listed.** Settings → Team shows the links still out —
69
- the address or "anyone with the link", role, workspaces, who made it, when
69
+ the address or "anyone with the link", role, projects, who made it, when
70
70
  it expires — with **Revoke** on each. The same list is
71
71
  `GET /api/team/invites` (`?all=1` adds accepted, revoked and expired ones)
72
72
  and `foldrun team invites`. The link itself is never listed: it is shown
@@ -74,12 +74,12 @@ invite with no address is a link for one person, whoever opens it first.
74
74
  - **Revoke one** with that button, `DELETE /api/team/invites/<id>` or
75
75
  `foldrun team invites revoke <id>`; its link stops working at once. An
76
76
  admin invite is the owner's to revoke, and a member scoped to some
77
- workspaces sees and revokes only the invites inside its scope.
77
+ projects sees and revokes only the invites inside its scope.
78
78
  - **Other things revoke them too.** A new invite to an address revokes the
79
79
  older ones still pending to it. Removing a member revokes every pending
80
80
  invite they made and any pending invite to their address — a removed
81
81
  member cannot rejoin with an old link. Lowering a member's role or
82
- narrowing their workspaces revokes the invites they made that they could
82
+ narrowing their projects revokes the invites they made that they could
83
83
  no longer make. An invite is also checked against its maker when it is
84
84
  accepted: if they have left or can no longer grant it, it is refused.
85
85
  - **Old links are refused.** Invite links made before 29 October 2026 were
@@ -94,8 +94,8 @@ Each revocation is in the audit log as `member.invite_revoked`;
94
94
 
95
95
  A key is minted with a role (`editor` unless you say otherwise) and acts as
96
96
  the account with that role. It can never be wider than the person who made
97
- it: not a higher role, and not a workspace they cannot open — a key minted
98
- by someone scoped to two workspaces is scoped to those two. Two things a key cannot do: act against a named
97
+ it: not a higher role, and not a project they cannot open — a key minted
98
+ by someone scoped to two projects is scoped to those two. Two things a key cannot do: act against a named
99
99
  member — inviting, re-roling, removing, transferring need a person,
100
100
  because a key names an account and never a who — and exceed its role.
101
101
 
@@ -103,7 +103,7 @@ One key is a person: the one your own `foldrun login` minted on your
103
103
  machine. From it you can manage the team — `foldrun team invite`, `team
104
104
  role`, `team access`, `team remove` — and set your own name and timezone
105
105
  (`foldrun me name`, `foldrun me timezone`). It acts at the lower of its role
106
- and yours now, in the workspaces both allow; a key is never an owner, so an
106
+ and yours now, in the projects both allow; a key is never an owner, so an
107
107
  owner's sign-in here is an admin, and inviting, changing or removing an admin
108
108
  stays in Settings → Team. The audit log marks each such act `via: foldrun
109
109
  login`. Transferring the account, your password, email, two-step sign-in and
@@ -115,23 +115,23 @@ than that, the owner's included, is not in its list.
115
115
  A key stays no wider than its maker **after** it is made, too. Remove a
116
116
  member and every key they minted in the account stops working at once —
117
117
  the one `foldrun login` made included. Lower their role, or narrow their
118
- workspaces, and each of their keys that would now reach more than they can
118
+ projects, and each of their keys that would now reach more than they can
119
119
  stops; they mint a new one at their new standing. Each such revocation is
120
120
  in the audit log (`apikey.revoked`, and `keysRevoked` on `member.removed`).
121
121
 
122
- A CI job or a contractor should hold a key that opens one workspace —
122
+ A CI job or a contractor should hold a key that opens one project —
123
123
  `foldrun keys create ci --workspaces leads`, or Settings → API keys. (Deploy
124
124
  keys, for the platform's own git, went with it on 17 October 2026; one
125
125
  minted before opens nothing.)
126
126
 
127
127
  A key **is** its account: the platform reads the account off the key, so one
128
- account's key can never reach another's workspaces. Someone who looks after
128
+ account's key can never reach another's projects. Someone who looks after
129
129
  several accounts — an agency, a reseller — holds one key per account and
130
130
  switches between them; the CLI stores each as a named profile. See
131
131
  [More than one account](cli#more-than-one-account).
132
132
 
133
133
  An **A2A key** is a key of its own kind, for an outside agent calling your
134
- published flows over [A2A](a2a): one workspace, the flows it names, and how
134
+ published flows over [A2A](a2a): one project, the flows it names, and how
135
135
  many tasks it may have open (`foldrun keys create partner --a2a --to leads
136
136
  --flows lead-finder`, or Settings → API keys). It opens only `/a2a/…` — every `/api`
137
137
  route refuses it — so it can never read runs, change files, approve a step or
@@ -151,7 +151,7 @@ from where — the address cut to its /24 (or /48 for IPv6), never the whole
151
151
  of it. Last use is written at most once a minute per key, so a busy CI key
152
152
  does not turn every request into a write.
153
153
 
154
- **Rotate** mints a new key with the old one's label, role, workspaces and
154
+ **Rotate** mints a new key with the old one's label, role, projects and
155
155
  deploy scope — and, if the old one had an end, the same lifetime from today —
156
156
  and ends the old key: at once, or after a grace of an hour or a day so a CI
157
157
  job can be moved across first. In the dashboard it is the Rotate button on
@@ -170,13 +170,13 @@ Settings → Audit log is the account's record of what people did: sign-ins
170
170
  (and refused ones), sign-outs and session revokes, password and email
171
171
  changes, MFA turned on or off, keys minted, rotated and revoked, invites,
172
172
  joins, role and scope changes, removals and ownership transfers, secrets
173
- set and deleted — **by name, never the value** — deploys, workspace deletes,
173
+ set and deleted — **by name, never the value** — deploys, project deletes,
174
174
  plan and billing changes, the account export and a close request, and every
175
175
  time support viewed the account. Filter by time, action, person or
176
- workspace, page back, and download it as CSV for an auditor.
176
+ project, page back, and download it as CSV for an auditor.
177
177
 
178
- The owner and admins who can open every workspace read it — people, or an
179
- `admin` key. A member or key scoped to some workspaces cannot: the log is
178
+ The owner and admins who can open every project read it — people, or an
179
+ `admin` key. A member or key scoped to some projects cannot: the log is
180
180
  the whole account's. It is the caller's own account, always; another
181
181
  account's entries are never in it. Entries are kept 365 days on the hosted platform (an install sets its own) — security
182
182
  evidence, [how long we keep what](security#what-we-keep-and-for-how-long) —