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/bin/foldrun.mjs +60 -60
- package/docs/a2a.md +12 -12
- package/docs/agents.md +21 -21
- package/docs/api-usage.md +2 -2
- package/docs/api.md +98 -98
- package/docs/assistant.md +21 -21
- package/docs/backups-and-restore.md +11 -11
- package/docs/budgets-and-billing.md +21 -21
- package/docs/checks.md +19 -19
- package/docs/cli.md +100 -100
- package/docs/coding-agents.md +8 -8
- package/docs/deploying.md +7 -7
- package/docs/evals.md +6 -6
- package/docs/extract.md +1 -1
- package/docs/faq.md +5 -5
- package/docs/feature-flags.md +1 -1
- package/docs/flows.md +14 -14
- package/docs/four-jobs.md +5 -5
- package/docs/getting-started.md +10 -10
- package/docs/glossary.md +9 -9
- package/docs/hooks.md +5 -5
- package/docs/how-it-works.md +1 -1
- package/docs/introduction.md +4 -4
- package/docs/knowledge-and-memory.md +6 -6
- package/docs/mcp.md +15 -15
- package/docs/network.md +9 -9
- package/docs/notifications.md +16 -16
- package/docs/oauth.md +1 -1
- package/docs/providers.md +6 -6
- package/docs/runs.md +28 -28
- package/docs/scheduling.md +1 -1
- package/docs/secrets.md +22 -22
- package/docs/security.md +15 -15
- package/docs/self-hosting.md +18 -18
- package/docs/status.md +1 -1
- package/docs/storage-and-sharing.md +14 -14
- package/docs/team-and-access.md +29 -29
- package/docs/tools.md +20 -20
- package/docs/troubleshooting.md +4 -4
- package/docs/workspaces.md +43 -43
- package/package.json +2 -2
- package/src/commands.mjs +131 -131
- package/src/guide.mjs +1 -1
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
|
|
7
|
-
git — which is what makes a
|
|
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
|
|
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 **
|
|
66
|
-
its
|
|
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
|
|
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
|
|
72
|
-
— your model provider, your email sender. Put it in a
|
|
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
|
|
75
|
+
### Limited to some projects
|
|
76
76
|
|
|
77
|
-
An account secret is open to every
|
|
78
|
-
credential with a few
|
|
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
|
|
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
|
-
|
|
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
|
|
106
|
-
leave it out. A
|
|
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
|
|
113
|
-
place on every list; deleting one takes it off first, so a new
|
|
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
|
-
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
350
|
-
|
|
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
|
|
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
|
|
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
|
|
package/docs/self-hosting.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
# Running it yourself
|
|
2
2
|
|
|
3
|
-
There are three places a
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
252
|
-
3. Watch the ops log: `records.on_files` (
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
100
|
+
project being redeployed.
|
|
101
101
|
|
|
102
102
|
## The account view
|
|
103
103
|
|
|
104
|
-
Storage at the account level lists every
|
|
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
|
|
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
|
|
109
|
-
**Upload** in the toolbar and pick the
|
|
110
|
-
a
|
|
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
|
package/docs/team-and-access.md
CHANGED
|
@@ -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 —
|
|
13
|
-
| **editor** | + edit files, upload, deploy (to a
|
|
14
|
-
| **admin** | + create and delete
|
|
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
|
|
26
|
+
### A project's policy is an admin's
|
|
27
27
|
|
|
28
|
-
The keys in a
|
|
29
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
49
|
-
one
|
|
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
|
|
55
|
-
another
|
|
56
|
-
everyone's
|
|
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
|
|
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,
|
|
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
|
-
|
|
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
|
|
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
|
|
98
|
-
by someone scoped to two
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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,
|
|
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,
|
|
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
|
-
|
|
176
|
+
project, page back, and download it as CSV for an auditor.
|
|
177
177
|
|
|
178
|
-
The owner and admins who can open every
|
|
179
|
-
`admin` key. A member or key scoped to some
|
|
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) —
|