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/assistant.md
CHANGED
|
@@ -2,15 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
The assistant is a panel on every page of the dashboard. Ask it how
|
|
4
4
|
foldrun works, or describe what you want built. It writes agents, flows,
|
|
5
|
-
tools and skills for a
|
|
5
|
+
tools and skills for a project and shows each one as a diff, checked, for
|
|
6
6
|
you to save.
|
|
7
7
|
|
|
8
8
|
Open it with **Ask AI** at the bottom right. **Draft with AI** on the Flows
|
|
9
9
|
page opens it too, with "Draft a flow that" ready to finish.
|
|
10
10
|
|
|
11
|
-
Inside a
|
|
11
|
+
Inside a project it works in that project. Anywhere else, such as the
|
|
12
12
|
account home, Billing or the docs, it works in the one chosen in its header;
|
|
13
|
-
your browser remembers the choice. Each
|
|
13
|
+
your browser remembers the choice. Each project keeps its own conversation.
|
|
14
14
|
|
|
15
15
|
## What it knows
|
|
16
16
|
|
|
@@ -20,11 +20,11 @@ Only three things:
|
|
|
20
20
|
it needs before it answers, and it cites what it used as
|
|
21
21
|
`[doc › section]`, which links to the heading. Under each reply,
|
|
22
22
|
**Read N doc sections** lists them.
|
|
23
|
-
- **This
|
|
23
|
+
- **This project's files**: its `AGENTS.md`, agents, flows, skills,
|
|
24
24
|
tools, hooks, knowledge, evals and scripts, plus the account library and
|
|
25
25
|
the account's `AGENTS.md`. It never reads `state/`, `storage/` or
|
|
26
26
|
secrets.
|
|
27
|
-
- **This
|
|
27
|
+
- **This project's runs**, when you ask about one: each step's status,
|
|
28
28
|
verify, errors and result, and one step in full. Run records are
|
|
29
29
|
redacted as they are written, so no secret value is in them.
|
|
30
30
|
|
|
@@ -38,7 +38,7 @@ treated as data, never as instructions to it.
|
|
|
38
38
|
A run that failed, or ended BAD or BLOCKED, has a **Doctor** button on its
|
|
39
39
|
page, and so does each [issue](runs#issues) under Needs attention and on the
|
|
40
40
|
Issues page, for the issue's newest run. It opens the assistant with "Doctor:
|
|
41
|
-
why did run <id> fail, and how do I fix it?" ready to send, in the
|
|
41
|
+
why did run <id> fail, and how do I fix it?" ready to send, in the project
|
|
42
42
|
that run is in — from the account home too. The assistant reads the run, then the
|
|
43
43
|
failing step in full and the files it names, and answers in this order:
|
|
44
44
|
|
|
@@ -74,22 +74,22 @@ Only these paths:
|
|
|
74
74
|
When something else needs to change, such as `AGENTS.md`, a secret or a
|
|
75
75
|
setting, it tells you what and where, and you make that change.
|
|
76
76
|
|
|
77
|
-
## New
|
|
77
|
+
## New projects
|
|
78
78
|
|
|
79
|
-
When you ask for a new
|
|
80
|
-
it proposes one: a name and what it is for, with a **Create
|
|
81
|
-
button. Creating it needs `workspace:manage` (admin or owner). The
|
|
79
|
+
When you ask for a new project, or describe a separate desk or pipeline,
|
|
80
|
+
it proposes one: a name and what it is for, with a **Create project**
|
|
81
|
+
button. Creating it needs `workspace:manage` (admin or owner). The project
|
|
82
82
|
starts blank, with only its `AGENTS.md`. The dashboard then opens it, and the
|
|
83
|
-
conversation carries on there: the assistant writes the new
|
|
83
|
+
conversation carries on there: the assistant writes the new project's
|
|
84
84
|
agents, flows, tools and skills for you to save.
|
|
85
85
|
|
|
86
|
-
It never proposes a name that is taken. An account with no
|
|
86
|
+
It never proposes a name that is taken. An account with no project yet
|
|
87
87
|
gets a box to name its first one.
|
|
88
88
|
|
|
89
89
|
Every file it proposes is checked as it writes it, and the model sees the
|
|
90
90
|
result and fixes errors before it finishes:
|
|
91
91
|
|
|
92
|
-
- the [deploy's own checks](deploying) and the flow lint, over the
|
|
92
|
+
- the [deploy's own checks](deploying) and the flow lint, over the project
|
|
93
93
|
as it would be with the file in it;
|
|
94
94
|
- a frontmatter key that appears nowhere in these docs is an error, because
|
|
95
95
|
foldrun would not read it;
|
|
@@ -109,16 +109,16 @@ the note "written with the assistant: …", which you can restore from
|
|
|
109
109
|
save is refused and nothing is overwritten; ask the assistant to propose it
|
|
110
110
|
again.
|
|
111
111
|
|
|
112
|
-
Saving is not deploying. On the platform, the saved file is the
|
|
112
|
+
Saving is not deploying. On the platform, the saved file is the project's
|
|
113
113
|
source, the same as an edit in the dashboard.
|
|
114
114
|
|
|
115
115
|
## History
|
|
116
116
|
|
|
117
117
|
Every reply is kept. **History** in the panel's header lists your
|
|
118
|
-
conversations, newest first and grouped by day, across every
|
|
118
|
+
conversations, newest first and grouped by day, across every project you
|
|
119
119
|
can see; type to search them, by title or by anything said in them. Open one
|
|
120
120
|
to carry it on: the files it proposed and you did not save come back with
|
|
121
|
-
it, and the panel moves to its
|
|
121
|
+
it, and the panel moves to its project. **New chat** starts another.
|
|
122
122
|
|
|
123
123
|
Conversations are yours alone. Nobody else in the account, owners included,
|
|
124
124
|
can list or read them; an API key's conversations belong to that key. Each
|
|
@@ -131,20 +131,20 @@ assistant workers, a pool of its own that grows with the queue, so a burst
|
|
|
131
131
|
of questions never slows the dashboard or takes a turn from your runs. At
|
|
132
132
|
most three replies of one account run at once; more wait their turn, and the
|
|
133
133
|
panel says so. The model only ever reads through the assistant's own tools,
|
|
134
|
-
on the server, scoped to your account and
|
|
134
|
+
on the server, scoped to your account and project; it runs no code and has
|
|
135
135
|
no network or shell of its own.
|
|
136
136
|
|
|
137
137
|
The workers themselves reach the internet at the model API and nowhere
|
|
138
|
-
else. A
|
|
139
|
-
saying so, not a timeout; that provider still serves the
|
|
138
|
+
else. A project whose `provider:` points at another address gets a reply
|
|
139
|
+
saying so, not a timeout; that provider still serves the project's runs.
|
|
140
140
|
|
|
141
141
|
## Who can use it, and what it costs
|
|
142
142
|
|
|
143
|
-
You need to be able to edit the
|
|
143
|
+
You need to be able to edit the project (`workspace:write`: editor,
|
|
144
144
|
admin or owner). Viewers do not see the button enabled.
|
|
145
145
|
|
|
146
146
|
Each reply is one model call that may use several tools, on the same models
|
|
147
|
-
your runs use: the
|
|
147
|
+
your runs use: the project's or account's own [provider](providers) or
|
|
148
148
|
key when there is one, otherwise the platform's. On the platform's models
|
|
149
149
|
the balance is checked first, and the reply is charged at the same price as
|
|
150
150
|
a run's tokens, as one line on [usage](budgets-and-billing), flow
|
|
@@ -5,7 +5,7 @@ different things:
|
|
|
5
5
|
|
|
6
6
|
| | What it brings back | Who does it | How far back |
|
|
7
7
|
|---|---|---|---|
|
|
8
|
-
| **A
|
|
8
|
+
| **A project's history** | its agents, flows, knowledge, skills, tools, scripts — the markdown | you, from Settings → Backups, `foldrun restore` or the API | every change it ever had |
|
|
9
9
|
| **A database dump before a migration** | the database: people, API keys, the ledger and every balance, the queue, the audit log | the platform team, when you ask | the last 10 deploys that changed the schema |
|
|
10
10
|
|
|
11
11
|
You do not need to switch either on.
|
|
@@ -28,8 +28,8 @@ It holds the database only, not the data volume.
|
|
|
28
28
|
|
|
29
29
|
### What it does not hold
|
|
30
30
|
|
|
31
|
-
-
|
|
32
|
-
|
|
31
|
+
- Project files, run records, `state/`, `memory/`, the vault and each
|
|
32
|
+
project's history: the data volume is not backed up. A project's
|
|
33
33
|
source can still be restored from its own history (below).
|
|
34
34
|
- **Storage file bytes.** These live in object storage (R2), not on the data
|
|
35
35
|
volume. *Unverified:* whether a storage file deleted by mistake can still
|
|
@@ -61,11 +61,11 @@ entry in `accounts`. Each record says `encrypted` and names the key it was
|
|
|
61
61
|
encrypted to by fingerprint (`recipient`, `sha256:` and 16 hex digits of the
|
|
62
62
|
public key).
|
|
63
63
|
|
|
64
|
-
## Restoring a
|
|
64
|
+
## Restoring a project yourself
|
|
65
65
|
|
|
66
|
-
Every change to a
|
|
66
|
+
Every change to a project — a dashboard save, a deploy, an import — is a
|
|
67
67
|
revision, and every revision keeps a snapshot of the whole source as it
|
|
68
|
-
stood right after it. Restoring puts the
|
|
68
|
+
stood right after it. Restoring puts the project's source back as it was
|
|
69
69
|
at one of them — the platform's own deploy history, so it works the same
|
|
70
70
|
whether or not you keep the source in git:
|
|
71
71
|
|
|
@@ -80,13 +80,13 @@ or before it — a time without a zone is read in the server's timezone, so
|
|
|
80
80
|
add `Z` or an offset to be exact), or an age: `90m`, `12h`, `3d`, `2w`.
|
|
81
81
|
A revision's diff is that one change; its snapshot is the whole source as
|
|
82
82
|
it stood on disk just after it, so two people saving at once each see the
|
|
83
|
-
other's change in their snapshot. History holds snapshots from 17 October 2026: each
|
|
83
|
+
other's change in their snapshot. History holds snapshots from 17 October 2026: each project's starts with
|
|
84
84
|
a "history starts here" revision, its source as it stood then, and nothing
|
|
85
85
|
before it can be restored this way.
|
|
86
86
|
|
|
87
87
|
- **Preview first.** The dry run lists every file that would change, come
|
|
88
88
|
back, or go, with a line diff. Nothing is written.
|
|
89
|
-
- **Confirm by name.** The restore itself needs the
|
|
89
|
+
- **Confirm by name.** The restore itself needs the project's name typed
|
|
90
90
|
back (`confirm` in the API). The CLI sends the removals you were shown, and
|
|
91
91
|
if anything else would now be removed — a file added in between — the
|
|
92
92
|
restore is refused and you are asked to look again.
|
|
@@ -108,7 +108,7 @@ POST /api/workspaces/<ws>/restore
|
|
|
108
108
|
{ "to": "<to.id from the dry run>", "confirm": "<ws>", "expectRemoved": [ … ] }
|
|
109
109
|
```
|
|
110
110
|
|
|
111
|
-
The
|
|
111
|
+
The project's History page lists every revision; open one and **Roll back
|
|
112
112
|
to this** does the same restore, by revision instead of by time, with its
|
|
113
113
|
preview first.
|
|
114
114
|
|
|
@@ -122,11 +122,11 @@ sealed half of the archive is deliberately not on the server, so it is done
|
|
|
122
122
|
by the platform team rather than by a button.
|
|
123
123
|
|
|
124
124
|
Settings → Backups → **Request a restore**: what (run records, `state/`,
|
|
125
|
-
storage, or everything), which
|
|
125
|
+
storage, or everything), which project (or all), the time you want back,
|
|
126
126
|
optionally the snapshot, and a note. The request is recorded, mailed to the
|
|
127
127
|
platform team and written to the audit log (`backup.restore_requested`); the
|
|
128
128
|
page lists your earlier requests. Asking needs the admin role and access to
|
|
129
|
-
every
|
|
129
|
+
every project.
|
|
130
130
|
|
|
131
131
|
```sh
|
|
132
132
|
foldrun backups request --what runs --at "2026-09-28 14:00" --to sales --note "a run record was deleted"
|
|
@@ -10,7 +10,7 @@ and no ceiling can spend in an hour what a month was meant to.
|
|
|
10
10
|
|---|---|---|
|
|
11
11
|
| **an agent, per run** | `budget: 2` in the agent's `agent.md` | the most that agent may spend in one run, across every step it takes in it — its step stops itself mid-turn at what is left, and a later step of its own in the same run is refused before it starts. Its steps running at once share what is left, as a group shares the run's: the copies of a fan-out split the cap, they are not each handed the whole of it |
|
|
12
12
|
| **a run** | `budget: 6` in a flow's frontmatter | a hard cap: between groups the next group does not start; within a group each step gets an equal share of the remainder and stops itself mid-turn when it is spent — the run cannot end over the cap |
|
|
13
|
-
| **a
|
|
13
|
+
| **a project, over time** | `budget: 60` in the project's `AGENTS.md`, or Settings | new runs refuse until the window turns |
|
|
14
14
|
| **the account, over time** | `budget: 500` in the account's `AGENTS.md`, or Settings | the same, for everything |
|
|
15
15
|
|
|
16
16
|
**Unset means no limit.** No file, no key, `budget: unlimited` — all the
|
|
@@ -27,7 +27,7 @@ wins, and the step's error says which line set it: `budget: in the flow
|
|
|
27
27
|
file` or `budget: on the writer agent`.
|
|
28
28
|
| **runs at once** | `concurrency: 3` in the account's `AGENTS.md`, or Settings → Policies → Governance | the fourth run waits its turn in the queue — never refused, only later. Empty means the install's share (`FOLDRUN_ACCOUNT_CONCURRENCY`), or no cap. Your own number can lower that, never raise it. Plans are not sold on runs at once but on [compute at once](#compute-at-four-levels): paid by the second, it is the real limit. On foldrun's hosted platform a ceiling on runs driven together guards against a loop gone wrong; it is not something a plan sells |
|
|
29
29
|
| **the queue lane** | the plan's lane (`high` \| `normal` \| `low`); `priority: low` in the account's `AGENTS.md` lowers it, and `high` there counts only with a plan that gives it | when slots are short, accounts take turns, weighted by lane — high 3, normal 2, low 1: every account's first run goes before anyone's second, a fast lane takes three turns to a slow lane's one and never all of them, an account with runs going waits behind one with none, and a run that has waited ten minutes moves up a turn. A flow's own `priority:` orders runs within that. The cap above still holds |
|
|
30
|
-
| **compute at once** | the plan's cores, GiB and disk (below); `compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }` in the account's `AGENTS.md`, or Settings → Policies → Governance, lowers it — and a
|
|
30
|
+
| **compute at once** | the plan's cores, GiB and disk (below); `compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }` in the account's `AGENTS.md`, or Settings → Policies → Governance, lowers it — and a project's and a flow's `compute:` narrow it further ([four levels](#compute-at-four-levels)) | what all the account's running steps may hold together — each step's cores, memory and disk, its `size:` class's or its own `resources:` ([agents](agents#resources--your-own-numbers)). A step that would pass it waits to start, like a full node — `room: waiting to start — 6 of this account's 8 GiB is held by its running steps…` — and starts in turn when one of the account's steps ends ([waiting for room](#waiting-for-room)). A step that **alone** is bigger than the pool, or than the plan's most for one step, fails at once with that message: no step finishing would make room. Without a plan, the install's `FOLDRUN_ACCOUNT_VCPU` / `FOLDRUN_ACCOUNT_MEMORY_GIB` / `FOLDRUN_ACCOUNT_DISK_GIB`, or no cap. Your own number can lower it, never raise it. `foldrun usage compute` shows the pool and what is held now. Enforced on the hosted platform and any k8s install; a self-hosted Docker install caps each step at its class but not the pool |
|
|
31
31
|
| **room to start** | the install's `FOLDRUN_RUN_MEMORY_GIB`, `FOLDRUN_RUN_DISK_GIB` and `FOLDRUN_ACCOUNT_PODS` | a step whose sandbox would not fit, or whose account already has its most sandboxes running, waits to start — `room: waiting to start — …` on its trail — instead of failing. The wait is not billed and has no time limit; the run page's start-up chip shows it as `room` ([waiting for room](#waiting-for-room)) |
|
|
32
32
|
|
|
33
33
|
A cap is a literal, never an expression, so it is readable off the file. The
|
|
@@ -43,11 +43,11 @@ by nothing at all, while the sandbox billed by the second. The platform sets
|
|
|
43
43
|
no clock of its own by design, so the cap is the only backstop there is, and
|
|
44
44
|
it counts everything.
|
|
45
45
|
|
|
46
|
-
The account's cap and a
|
|
47
|
-
the
|
|
46
|
+
The account's cap and a project's are checked separately and both apply:
|
|
47
|
+
the project one stops that desk, the account one stops everything.
|
|
48
48
|
|
|
49
49
|
**A cap over time warns before it refuses.** At 80% and again at 95% of a
|
|
50
|
-
|
|
50
|
+
project's `budget:`, the project's notification destination is told what
|
|
51
51
|
has been spent and what happens at the cap. Each mark is sent once per
|
|
52
52
|
window — today, this week, this month, whichever the cap is over — and
|
|
53
53
|
resets when the cap does. Without it the way a customer learns about the
|
|
@@ -56,7 +56,7 @@ cap is a desk failing to start on a Tuesday.
|
|
|
56
56
|
Size the run cap from the run records, at two or three times the median — real
|
|
57
57
|
work never trips it, a runaway is stopped where it went wrong, and the
|
|
58
58
|
failure notification says why. The dashboard's Usage page shows spend by
|
|
59
|
-
|
|
59
|
+
project and by meter.
|
|
60
60
|
|
|
61
61
|
### Compute at four levels
|
|
62
62
|
|
|
@@ -66,7 +66,7 @@ level only narrows the one above it; a step must fit all of them.
|
|
|
66
66
|
| level | where | what it caps |
|
|
67
67
|
|---|---|---|
|
|
68
68
|
| **account** | the plan (or the install's `FOLDRUN_ACCOUNT_*`); `compute:` in the account's `AGENTS.md`, Settings → Policies → Governance or `foldrun account set compute` lowers it | everything the account's running steps hold together |
|
|
69
|
-
| **
|
|
69
|
+
| **project** | `compute:` in the project's `AGENTS.md`, its Settings → Policies → Governance, or `foldrun workspace set compute … --to <ws>` | what that project's running steps hold together |
|
|
70
70
|
| **run** | `compute:` in the flow, the flow's card, or `foldrun flow compute <flow> …` | what one run of the flow holds at once across its parallel steps — each run has its own |
|
|
71
71
|
| **step** | the agent's `size:` or `resources: { cpu, memory, disk }`; the plan's (or install's `FOLDRUN_STEP_MAX_*`) most for one step — on foldrun's hosted platform an account without a plan, or whose plan sets none, gets the entry plan's | one step's sandbox |
|
|
72
72
|
|
|
@@ -78,16 +78,16 @@ compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }
|
|
|
78
78
|
Any of the three may be left out. A step that would pass a cap waits, in
|
|
79
79
|
turn, and its trail says which level holds it — `room: waiting to start —
|
|
80
80
|
3 of this run's 4 vCPU is held by its running steps…`. A step that **alone**
|
|
81
|
-
is bigger than a level's whole cap fails at once, naming it. A
|
|
81
|
+
is bigger than a level's whole cap fails at once, naming it. A project's
|
|
82
82
|
figure above the account's grants nothing: the account's still applies.
|
|
83
83
|
`foldrun usage compute` and `GET /api/usage/compute` show every level — the
|
|
84
|
-
account, each
|
|
85
|
-
27 Oct 2026 a
|
|
86
|
-
|
|
84
|
+
account, each project and each live run — with what it holds. Before
|
|
85
|
+
27 Oct 2026 a project's `compute:` was read nowhere; it now caps that
|
|
86
|
+
project.
|
|
87
87
|
|
|
88
88
|
### Waiting for room
|
|
89
89
|
|
|
90
|
-
A step that finds no room — its run's,
|
|
90
|
+
A step that finds no room — its run's, project's or account's pool, its
|
|
91
91
|
account's most sandboxes at once, or the node's memory or disk —
|
|
92
92
|
**waits; a wait never fails a step**. There
|
|
93
93
|
is no time limit (until 27 Oct 2026 a step failed after 30 minutes). Only a
|
|
@@ -109,13 +109,13 @@ fails, at once, because nothing finishing would make room.
|
|
|
109
109
|
- **Seen.** The run page says *Waiting for room to start*, why, and since
|
|
110
110
|
when; Settings → Policies → Governance and `foldrun usage compute` list every
|
|
111
111
|
waiting step, oldest first (`waiting` in `GET /api/usage/compute`).
|
|
112
|
-
- **Told.** After an hour (`FOLDRUN_ROOM_ALERT_MIN`) the
|
|
112
|
+
- **Told.** After an hour (`FOLDRUN_ROOM_ALERT_MIN`) the project's
|
|
113
113
|
`notify:` hears of it once, as event `room`, with what to change: ask for
|
|
114
114
|
less (`size:`, `resources:`) or allow the account more compute.
|
|
115
115
|
|
|
116
116
|
- **In turn, by scope.** An older step goes first among the steps of the
|
|
117
117
|
scope that holds it back: its run's own pool among that run's steps, its
|
|
118
|
-
|
|
118
|
+
project's among that project's, otherwise among all its account's —
|
|
119
119
|
so a step stuck behind a narrow pool of its own never holds back the rest.
|
|
120
120
|
|
|
121
121
|
Nothing is charged while a step waits — the meter starts when its sandbox
|
|
@@ -155,7 +155,7 @@ that is running.
|
|
|
155
155
|
over A2A is told the agent is busy.
|
|
156
156
|
- **A trigger that fires into it is skipped, not delayed.** A schedule's
|
|
157
157
|
fire, a watched page's change, a debounced burst, a chained or storage
|
|
158
|
-
trigger: each is written on the
|
|
158
|
+
trigger: each is written on the project's Triggers page as
|
|
159
159
|
*too many runs waiting*, with the sentence, and the flow waits for its
|
|
160
160
|
next fire. (A webhook's sender retries; nothing else does.)
|
|
161
161
|
- **A threshold, not a ceiling.** The limit is checked when a new run is
|
|
@@ -219,7 +219,7 @@ none — are **1¢ each**; the falling figure below is what a plan's bundle
|
|
|
219
219
|
works out to, and it is the reason to pick a bigger plan rather than buy
|
|
220
220
|
more credits.
|
|
221
221
|
|
|
222
|
-
| plan | a month | credits a month | storage included | compute at once | one step, at most |
|
|
222
|
+
| plan | a month | credits a month | storage included | compute at once | one step, at most | projects | queue lane |
|
|
223
223
|
|---|---|---|---|---|---|---|---|
|
|
224
224
|
| **Free** | $0 | 300 | 2 GB | 2 vCPU · 4 GiB · 20 GiB disk | 2 vCPU · 4 GiB · 10 GiB disk | 2 | normal |
|
|
225
225
|
| **Starter** | $29 | 3,000 | 10 GB | 4 vCPU · 8 GiB · 40 GiB disk | 4 vCPU · 8 GiB · 20 GiB disk | 5 | normal |
|
|
@@ -339,10 +339,10 @@ provider's own invoice.
|
|
|
339
339
|
| **vCPU** | per second, the cores a step reserves while it runs |
|
|
340
340
|
| **RAM** | per second, the GiB a step reserves while it runs |
|
|
341
341
|
| **step disk** | per second, the GiB of disk the step may write; deleted when the step ends |
|
|
342
|
-
| **storage** | per GB-month, the files you keep between runs **over your plan's allowance**, accrued daily. Only the GB above what your plan includes are charged (Free 2 GB, Starter 10, Pro 100, Scale 1 TB). It counts your
|
|
342
|
+
| **storage** | per GB-month, the files you keep between runs **over your plan's allowance**, accrued daily. Only the GB above what your plan includes are charged (Free 2 GB, Starter 10, Pro 100, Scale 1 TB). It counts your projects' files and your run history, as they are now; a GB is 2^30 bytes |
|
|
343
343
|
| **network** | per GB the sandbox moves, both directions |
|
|
344
344
|
| **search and browser pods** | an account's search engine and its browser run as pods of their own. Each is charged like a step: the vCPU and GiB it holds, for the seconds it lives (idle time included, until it is let go), at the same vCPU and RAM rates, plus the GB it moves at the network rate. A search pod holds 0.25 vCPU and 0.75 GiB and a browser pod 1 vCPU, 3 GiB and 4 GiB of disk by default; the platform's operator sets these sizes, so the size shown is the one in force. Each pod's requests equal its limits, so you are charged for exactly what is reserved for it, at the size the pod was made with. A pod session is not a run, so no minimum run charge applies |
|
|
345
|
-
| **warm builds** | when you deploy, your
|
|
345
|
+
| **warm builds** | when you deploy, your project's environments (the packages an agent declares) are built ahead of its first step, in a short pod. **You pay for it**, because it is the work the first step would otherwise have done in its own sandbox: a small sandbox's vCPU and RAM for the seconds it ran, and the GB it downloaded. It is bounded (one build at a time, ten minutes at most) and shown as its own line, so it is never hidden in another |
|
|
346
346
|
|
|
347
347
|
The rates are on the Usage page's **Rates** tab, in `foldrun usage rates`,
|
|
348
348
|
in `GET /api/usage/rates` and, for anyone, in the public
|
|
@@ -494,7 +494,7 @@ avatar, with eight tabs:
|
|
|
494
494
|
| **Invoices** | a tax invoice for every card payment — the plan's fee and each top-up — hosted by Stripe, and a statement for every month; `foldrun billing invoices` lists the invoices and receipts in a terminal |
|
|
495
495
|
| **Payment** | the saved card and the auto top-up rule, with defaults derived from the burn |
|
|
496
496
|
| **Details** | who the invoices are made out to: legal name, ABN, address and the invoice email |
|
|
497
|
-
| **Spend limits** | the account's cap and each
|
|
497
|
+
| **Spend limits** | the account's cap and each project's — over a day, a week or a month — as bars with the warning marks drawn where they fire, editable in place; `foldrun usage budget` shows the same standing in a terminal |
|
|
498
498
|
|
|
499
499
|
The balance also sits in the header of every page, tinted by runway, and a
|
|
500
500
|
banner appears across the dashboard when the balance is under a week's cover
|
|
@@ -542,7 +542,7 @@ the platform's operator suspended for another reason stays suspended. The
|
|
|
542
542
|
operator sees where it stands on the customer's overview.
|
|
543
543
|
|
|
544
544
|
**Your data, and leaving.** Settings → Your data gives the owner one JSON
|
|
545
|
-
file with the account's
|
|
545
|
+
file with the account's projects, members, an index of every run and the
|
|
546
546
|
whole ledger (`GET /api/account/export`). The same place holds **Close
|
|
547
547
|
account**: type the account's name and it is suspended at once — no new
|
|
548
548
|
runs, schedules stop firing — while the platform team settles the last
|
|
@@ -701,7 +701,7 @@ that was handled changes nothing.
|
|
|
701
701
|
## Plan gates
|
|
702
702
|
|
|
703
703
|
Two more limits come with the plan rather than the wallet: how many
|
|
704
|
-
|
|
704
|
+
projects an account may create (beyond it, creation refuses with `402`),
|
|
705
705
|
and how many runs may execute in parallel (beyond it, runs **wait** — they
|
|
706
706
|
are never refused, because a queued run is work that will happen and a
|
|
707
707
|
refused one is work that will not).
|
package/docs/checks.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Checks
|
|
2
2
|
|
|
3
|
-
`foldrun check` answers two questions about a
|
|
3
|
+
`foldrun check` answers two questions about a project before anything
|
|
4
4
|
runs: **will it run?** (a tool that exists, a step that names a real agent,
|
|
5
5
|
an option the parser can read) and **is it safe to run?** (a key pasted into
|
|
6
6
|
a prompt, a knowledge file carrying hidden instructions, an agent that reads
|
|
@@ -19,12 +19,12 @@ foldrun check --rules # every rule, its level, what it guards again
|
|
|
19
19
|
The same findings appear in four other places, from the same rules in
|
|
20
20
|
`@foldrun/core`:
|
|
21
21
|
|
|
22
|
-
- **The dashboard**: the
|
|
22
|
+
- **The dashboard**: the project's **Checks** page lists every finding on
|
|
23
23
|
the deployed copy, grouped by rule, each linking to its file. The editor
|
|
24
24
|
shows a file's own findings above it.
|
|
25
25
|
- **The API**: `GET /api/workspaces/<ws>/check` answers with the same
|
|
26
26
|
findings as JSON (`?security=1`, `?rule=`). See [api](api).
|
|
27
|
-
- **A save**: saving a file in the dashboard editor checks the
|
|
27
|
+
- **A save**: saving a file in the dashboard editor checks the project as
|
|
28
28
|
it would be with that file. An error a deploy would refuse is refused
|
|
29
29
|
there too and nothing is written, because a saved file goes live at once;
|
|
30
30
|
**Save anyway** writes it. Warnings never stop a save. A History restore
|
|
@@ -52,7 +52,7 @@ are enough to find it, and too few to use it.
|
|
|
52
52
|
| `warn` | it works, and something about it should change | with `--fail-on warn` or `--security` |
|
|
53
53
|
| `info` | worth knowing; often a judgement call | with `--fail-on info` |
|
|
54
54
|
|
|
55
|
-
Every rule added with the scanner is a warning for now, so a
|
|
55
|
+
Every rule added with the scanner is a warning for now, so a project that
|
|
56
56
|
passed yesterday still passes. To fail a build on them, use `--security` (which
|
|
57
57
|
fails on a warning) or `--fail-on warn`.
|
|
58
58
|
|
|
@@ -80,8 +80,8 @@ listed with it. `deploy_block:` in `AGENTS.md` turns them into refusals:
|
|
|
80
80
|
| `secrets` | a key or password written into a file (`secret/hardcoded`) |
|
|
81
81
|
| `security` | any security finding: `secret/*`, `content/*`, `security/*`, `supply-chain/*`, and `flow/outward-ungated` (a step that acts outside with no check or approval) |
|
|
82
82
|
|
|
83
|
-
Set it in the account's `AGENTS.md` for every
|
|
84
|
-
|
|
83
|
+
Set it in the account's `AGENTS.md` for every project, or in one
|
|
84
|
+
project's `AGENTS.md`, which wins. Settings → Policies → Governance → **Refuse a
|
|
85
85
|
deploy on**, or `foldrun account set deploy_block secrets`. A refused
|
|
86
86
|
deploy names each finding and its rule; a `foldrun-ignore` with a reason
|
|
87
87
|
(below) still accepts one.
|
|
@@ -98,11 +98,11 @@ and the tool text of MCP servers reached by URL
|
|
|
98
98
|
--online`, or `GET /api/workspaces/<ws>/check?online=1` — editor and
|
|
99
99
|
above, since it sends the platform out to OSV and your MCP servers. The
|
|
100
100
|
answer is kept for 10 minutes while the files are unchanged, and a
|
|
101
|
-
|
|
102
|
-
- **Every day by itself:** the platform rescans every
|
|
101
|
+
project gets six fresh online passes per 10 minutes.
|
|
102
|
+
- **Every day by itself:** the platform rescans every project, offline and
|
|
103
103
|
online. The first rescan of each source records what is there. After
|
|
104
104
|
that, a security finding that was not there before goes to the
|
|
105
|
-
|
|
105
|
+
project's `notify:` as the `security` event, once. A finding that goes
|
|
106
106
|
away and comes back is new again.
|
|
107
107
|
- **What is never done:** a server started as a command is never run to
|
|
108
108
|
check it, and no credential is sent. A server that needs one is reported
|
|
@@ -141,9 +141,9 @@ Ignores in `memory/` are not honoured. Agents write their memory
|
|
|
141
141
|
themselves, so an ignore there could have been written by whatever an agent
|
|
142
142
|
read: an injection that silences its own finding.
|
|
143
143
|
|
|
144
|
-
## Adopting it on an existing
|
|
144
|
+
## Adopting it on an existing project
|
|
145
145
|
|
|
146
|
-
A
|
|
146
|
+
A project with years of history will have findings on day one. Do not fix
|
|
147
147
|
them all before the check can be useful:
|
|
148
148
|
|
|
149
149
|
```sh
|
|
@@ -200,7 +200,7 @@ Hugging Face, Linear, DigitalOcean, Shopify, Resend or foldrun key (`fr_api_`, `
|
|
|
200
200
|
`fr_a2a_`, `fr_dep_`, and the older `mda_`/`mdk_`), a JSON web token,
|
|
201
201
|
a private key, a webhook URL that carries its own secret, a password inside a
|
|
202
202
|
URL, or a field named like a credential (`api_key:`, `token:`, `password=`)
|
|
203
|
-
holding a literal value that looks random. Everything in a
|
|
203
|
+
holding a literal value that looks random. Everything in a project is
|
|
204
204
|
deployed, versioned, readable by every agent and shown to the model.
|
|
205
205
|
|
|
206
206
|
Move it to the vault (`foldrun secrets set NAME`), write `${NAME}` where it
|
|
@@ -300,7 +300,7 @@ Take a leg away:
|
|
|
300
300
|
[api.example.com] }`, or `network: trusted` ([Network](network)). A bare
|
|
301
301
|
list of sites only adds to a level, so an agent that reads the web stays
|
|
302
302
|
`open` with one. The level is resolved the way a run resolves it: the
|
|
303
|
-
agent's, then the
|
|
303
|
+
agent's, then the project's `AGENTS.md`, then the account's;
|
|
304
304
|
- split it into a reader with no secrets and a sender that reads nothing
|
|
305
305
|
untrusted;
|
|
306
306
|
- guard its calls with a `hooks:` gate ([Hooks](hooks)).
|
|
@@ -356,7 +356,7 @@ platform does not count one that is bound.
|
|
|
356
356
|
### security/published-flow-ungated
|
|
357
357
|
|
|
358
358
|
*warn · ASI02, ASI09.* A flow published over A2A has a step that acts outside
|
|
359
|
-
the
|
|
359
|
+
the project — an `outward: true` tool, an API it may write to, or a message
|
|
360
360
|
to an outside agent (`remotes:`) — with no approval (`!`) and no `ask:` on it,
|
|
361
361
|
on a step beside it in its group (a gate there holds the whole group), or on a
|
|
362
362
|
step before it. Anyone holding a key for the flow can start it as
|
|
@@ -375,7 +375,7 @@ again. An error in `foldrun check`, a warning at deploy.
|
|
|
375
375
|
|
|
376
376
|
*warn · ASI04, ASI05.* `curl … | sh` (or `wget`, `bash`, `zsh`) runs whatever
|
|
377
377
|
the server returns today, unreviewed, in the sandbox that holds the
|
|
378
|
-
|
|
378
|
+
project. Declare the package under `runtime: system:` or `packages:`, or
|
|
379
379
|
download it, verify a checksum, then run it.
|
|
380
380
|
|
|
381
381
|
### supply-chain/unpinned-mcp
|
|
@@ -483,7 +483,7 @@ changes provider. Write a level the model has, or choose a provider whose
|
|
|
483
483
|
model has the one you want (Settings → Models). Checked on the
|
|
484
484
|
platform (the Checks page, a save, a deploy) when the account runs on
|
|
485
485
|
foldrun's models; `foldrun check` offline does not know the account's
|
|
486
|
-
choice, and an agent or
|
|
486
|
+
choice, and an agent or project with its own `provider:` is not checked.
|
|
487
487
|
|
|
488
488
|
### config/conflict
|
|
489
489
|
|
|
@@ -513,7 +513,7 @@ value and trying again. But the dashboard editor and the source API refuse
|
|
|
513
513
|
to save it, and other tools that read skills may not load it. When even the
|
|
514
514
|
second read fails, the skill has no name or description and is never loaded.
|
|
515
515
|
For the account library's agents, tools and hooks, the runtime cannot read
|
|
516
|
-
the file at all. A
|
|
516
|
+
the file at all. A project's own agent, flow, tool, eval, hook or
|
|
517
517
|
`AGENTS.md` with broken YAML is not this warning: a deploy refuses it, under
|
|
518
518
|
that file's own rule (`agent/config`, `flow/config` …).
|
|
519
519
|
|
|
@@ -551,10 +551,10 @@ URL is fetched.
|
|
|
551
551
|
|
|
552
552
|
On the platform (the Checks page, the editor, `GET …/check` and the daily
|
|
553
553
|
rescan) the checks read a bounded amount. In `state/` and `memory/` (the
|
|
554
|
-
|
|
554
|
+
project's, or one agent's), which is what agents write as they run, a file
|
|
555
555
|
over 5 MiB is not read, and nor is anything past 32 MiB or 5,000 files in all.
|
|
556
556
|
The rescan lists what it left out, and keeps what it found in those files
|
|
557
|
-
before. If everything else in the
|
|
557
|
+
before. If everything else in the project is over 64 MiB, the project is
|
|
558
558
|
not checked at all, and the check says so (`GET …/check` answers 413).
|
|
559
559
|
`foldrun check` on your own machine reads everything.
|
|
560
560
|
|