foldrun 17.1.0 → 17.1.2
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/agents.md +20 -4
- package/docs/checks.md +17 -0
- package/docs/network.md +46 -13
- package/docs/security.md +29 -0
- package/package.json +1 -1
package/docs/agents.md
CHANGED
|
@@ -524,7 +524,20 @@ snapshot beside the old one the first time the set is needed — the run log
|
|
|
524
524
|
then says `(apt, 30s, 1 snapshot did not fit this image)`. A snapshot is
|
|
525
525
|
rebuilt 14 days after it was made, so the packages in it pick up Debian's
|
|
526
526
|
fixes. The run log says `system packages ready: … (snapshot, 1s)` or
|
|
527
|
-
`(apt, 30s)`, or fails the step with apt's own reason.
|
|
527
|
+
`(apt, 30s)`, or fails the step with apt's own reason.
|
|
528
|
+
|
|
529
|
+
A snapshot is written into the account's runtime cache, which steps can
|
|
530
|
+
write — and it is restored as root. So it is **sealed**: the platform keeps a
|
|
531
|
+
key for each account that steps never see, and a snapshot is restored only if
|
|
532
|
+
its seal, made with that key when the start-up built it, matches the package
|
|
533
|
+
set, the image and every byte of the file. A snapshot a step rewrote, or one
|
|
534
|
+
whose seal does not match, is not restored; the step installs with apt and the
|
|
535
|
+
run log says why on the next line — `snapshot refused: its contents do not
|
|
536
|
+
match its seal`. Even a sealed snapshot can only put package files where
|
|
537
|
+
packages go (`/etc`, `/usr`, `/var`, `/opt`), never a setuid file, a device,
|
|
538
|
+
or anything through a link or a folder a step could change. A package set
|
|
539
|
+
that installs a setuid program is installed with apt every time
|
|
540
|
+
(`no snapshot kept: … is setuid or setgid`). On a laptop (`foldrun run` with no container) there is nothing to
|
|
528
541
|
install into: the list is reported as assumed present.
|
|
529
542
|
|
|
530
543
|
Manim, for one, needs all four of its kinds at once:
|
|
@@ -585,9 +598,12 @@ destroyed when the step ends.
|
|
|
585
598
|
The agent is never root. A Debian package is installed by a small helper the
|
|
586
599
|
container's root start-up leaves running before it drops to the agent user;
|
|
587
600
|
the agent can only ask it, by name, and each name is checked against Debian's
|
|
588
|
-
naming rule, so nothing but a package name reaches apt. It
|
|
589
|
-
|
|
590
|
-
|
|
601
|
+
naming rule, so nothing but a package name reaches apt. It restores the same
|
|
602
|
+
snapshots as `runtime: system:`, so a set the account's steps declare is back
|
|
603
|
+
in about a second; it never saves one, because it runs beside the agent's own
|
|
604
|
+
code, and only a step's start-up, before any of that code exists, seals a
|
|
605
|
+
snapshot. Declare a package in `runtime: system:` to have it from a snapshot.
|
|
606
|
+
pip and npm packages need no root
|
|
591
607
|
and are installed as the agent, into a directory of the step's own.
|
|
592
608
|
|
|
593
609
|
A pip or npm package runs none of its own code on the way in. npm installs
|
package/docs/checks.md
CHANGED
|
@@ -223,6 +223,23 @@ it. The finding never repeats the value, and neither does any answer that
|
|
|
223
223
|
shows the setting (notify's test send names the secret, or says it is not a
|
|
224
224
|
name).
|
|
225
225
|
|
|
226
|
+
### secret/reserved-env-name
|
|
227
|
+
|
|
228
|
+
*warn · ASI03, ASI05.* An agent's or a tool's `secrets:` names a variable
|
|
229
|
+
that steers programs rather than carries data: `LD_PRELOAD` and every other
|
|
230
|
+
`LD_*`, `PATH`, `IFS`, `HOME`, `SHELL`, `BASH_ENV`, `ENV`, `CDPATH`,
|
|
231
|
+
`NODE_OPTIONS`, `PYTHONPATH`, `PYTHONSTARTUP`, `PERL5OPT`, `RUBYOPT`,
|
|
232
|
+
`GCONV_PATH` and their like. A secret reaches the sandbox as an environment
|
|
233
|
+
variable of its own name, so one called `LD_PRELOAD` loads its value into
|
|
234
|
+
every program the agent starts, and one called `PATH` decides which program
|
|
235
|
+
answers to `python3`. That is almost never what was meant, and a value that
|
|
236
|
+
points into a folder the agent writes runs whatever is put there.
|
|
237
|
+
|
|
238
|
+
The platform does not depend on it: the part of a step's start-up that runs
|
|
239
|
+
as root never reads the step's environment, so it is the agent's own
|
|
240
|
+
sandbox at stake. Give the secret a name of its own (`STRIPE_KEY`,
|
|
241
|
+
`CRM_TOKEN`) and have the script read that.
|
|
242
|
+
|
|
226
243
|
### content/hidden-unicode
|
|
227
244
|
|
|
228
245
|
*warn · ASI01, ASI04, ASI06.* Zero-width characters, bidirectional overrides
|
package/docs/network.md
CHANGED
|
@@ -124,13 +124,43 @@ step's list and checks every connection against it:
|
|
|
124
124
|
- a site **on the list** is a tunnel: the bytes pass through and the proxy
|
|
125
125
|
never reads them;
|
|
126
126
|
- a site a **secret is bound to** is intercepted, so the secret can be filled
|
|
127
|
-
in on the way out ([Secrets](secrets#bound-to-sites)).
|
|
127
|
+
in on the way out ([Secrets](secrets#bound-to-sites)). That holds for a
|
|
128
|
+
WebSocket too: a `wss://` to such a site has its opening request filled
|
|
129
|
+
like any other (URL, headers, Basic auth), and once the site agrees the
|
|
130
|
+
messages pass both ways unread. The platform's own model keys are never
|
|
131
|
+
sent over one, and a [test run](runs#test-runs) may open one only to a site it
|
|
132
|
+
could not write to.
|
|
128
133
|
|
|
129
134
|
On a cluster the pod's network policy backs this up. A step whose level is
|
|
130
|
-
`trusted` or `none` runs in a pod that may reach the proxy and
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
135
|
+
`trusted` or `none` runs in a pod that may reach the proxy and nothing else,
|
|
136
|
+
so a program that ignores the proxy variables finds no route instead of
|
|
137
|
+
going round the list; it cannot reach the account's browser or search pods
|
|
138
|
+
either, which are the world fetched on a run's behalf.
|
|
139
|
+
|
|
140
|
+
### DNS
|
|
141
|
+
|
|
142
|
+
A name is a message too: looking up `<anything>.example.net` reaches
|
|
143
|
+
example.net's nameserver, whatever the list says. So on a cluster that walls
|
|
144
|
+
it (`FOLDRUN_RUN_DNS_WALL=1`, on with foldrun's own manifests), a pod held to
|
|
145
|
+
its list has **no DNS of its own**: no resolver to ask, and the cluster's
|
|
146
|
+
resolver is not reachable from it. It does not need one. Every program sends
|
|
147
|
+
the proxy the name of the site it wants (`CONNECT api.example.com:443`), the
|
|
148
|
+
proxy looks up only a site the list allows, and the proxy's own address is
|
|
149
|
+
written into the pod. curl, Python's requests and httpx, Node, Go, git, apt,
|
|
150
|
+
pip, npm, the Claude CLI and the browser all work this way. The trace says
|
|
151
|
+
so:
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
dns: this sandbox has no resolver of its own — every site is reached through the egress proxy by name, and the proxy looks up only sites on the list; a program that looks a name up itself (dig, an MX check, a client that resolves before it connects) fails here
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
What fails there is what asks DNS directly: `dig`, `nslookup`, `ping` by
|
|
158
|
+
name, a mail-address check that looks up MX records, a library that resolves
|
|
159
|
+
a name before it connects. Give such an agent the site of a DNS-over-HTTPS
|
|
160
|
+
service in its list (`dns.google`, `cloudflare-dns.com`) and ask that over
|
|
161
|
+
HTTPS, or give it `network: open`. What the wall cannot hold is what the
|
|
162
|
+
list itself allows: the proxy looks up a name under an allowed wildcard
|
|
163
|
+
site (`*.example.com`), and a tunnel to an allowed host may use any port.
|
|
134
164
|
|
|
135
165
|
The trace opens with the step's network:
|
|
136
166
|
|
|
@@ -167,7 +197,8 @@ then switch it on. The trace line `network: … — report only` says which
|
|
|
167
197
|
mode a step ran in.
|
|
168
198
|
|
|
169
199
|
On a cluster, a refused step's pod also loses its direct route to the
|
|
170
|
-
world: the network policy gives it the proxy and DNS
|
|
200
|
+
world: the network policy gives it the proxy only (and DNS, on a cluster
|
|
201
|
+
that does not wall it).
|
|
171
202
|
|
|
172
203
|
### Where it is not held
|
|
173
204
|
|
|
@@ -184,16 +215,19 @@ A step that may **browse** with the `web` tool is held to its list where the
|
|
|
184
215
|
platform can wall the step in: on a cluster whose operator has switched it
|
|
185
216
|
on (`FOLDRUN_BROWSE_ENFORCE=1`), for a step whose list is restricted
|
|
186
217
|
(`trusted` or `none`) and enforced. Such a step gets the proxy like any
|
|
187
|
-
other, its pod is walled to the egress proxy and
|
|
188
|
-
inside that pod — the step's own, shared with no other step. Whatever the
|
|
218
|
+
other, its pod is walled to the egress proxy (and, where the cluster walls
|
|
219
|
+
it, has no [DNS](#dns) of its own), and the browser runs inside that pod — the step's own, shared with no other step. Whatever the
|
|
189
220
|
browser is told — another proxy, a new context with a proxy of its own, a
|
|
190
221
|
page's script — the only way out is the egress proxy, which holds the list
|
|
191
222
|
per connection, over IPv4 and IPv6, TCP and UDP alike. The trace says so —
|
|
192
223
|
|
|
193
224
|
```
|
|
194
|
-
network: trusted (agent) — the trusted list (207 sites); added: example.com — enforced — hosted: the browser runs inside this step's sandbox, whose network reaches only the egress proxy (which holds the list)
|
|
225
|
+
network: trusted (agent) — the trusted list (207 sites); added: example.com — enforced — hosted: the browser runs inside this step's sandbox, whose network reaches only the egress proxy (which holds the list), so a page, a script or a changed proxy setting reaches no site off the list.
|
|
195
226
|
```
|
|
196
227
|
|
|
228
|
+
followed by the `dns:` line above, or, on a cluster that does not wall DNS,
|
|
229
|
+
one saying the sandbox can still look any name up.
|
|
230
|
+
|
|
197
231
|
A site off the list fails in the browser as a failed tunnel
|
|
198
232
|
(`ERR_TUNNEL_CONNECTION_FAILED`), and the trace names it with the usual
|
|
199
233
|
advice: add just that site.
|
|
@@ -222,10 +256,9 @@ What a held step does differently:
|
|
|
222
256
|
walled pod either; the trace says so. Name a search provider in `web:`
|
|
223
257
|
(it goes through the proxy) or leave search out of that step.
|
|
224
258
|
|
|
225
|
-
Not covered: DNS lookups
|
|
226
|
-
DNS, and
|
|
227
|
-
|
|
228
|
-
a page loads inside a connection to an allowed site.
|
|
259
|
+
Not covered: DNS lookups on a cluster that does not wall them (see
|
|
260
|
+
[DNS](#dns)), and — as for every tunnel — which origins a page loads inside
|
|
261
|
+
a connection to an allowed site.
|
|
229
262
|
|
|
230
263
|
Everywhere else — `foldrun run` on your machine, the single-container tier,
|
|
231
264
|
an install without the switch, a report-only list, `network: open` — a
|
package/docs/security.md
CHANGED
|
@@ -17,6 +17,20 @@ Startup is under a second warm, so this is not the latency it sounds like;
|
|
|
17
17
|
it is the boundary that lets one account's agent and another's share a
|
|
18
18
|
machine.
|
|
19
19
|
|
|
20
|
+
What a sandbox keeps between steps is the account's runtime cache: the
|
|
21
|
+
environments its `runtime:` declares, built once and reused. Steps write it,
|
|
22
|
+
so nothing in it is trusted by the part of a step's start-up that runs as
|
|
23
|
+
root. That part never holds the step's environment: secrets are exported
|
|
24
|
+
under the names their author chose, and one called `LD_PRELOAD` or `PATH`
|
|
25
|
+
pointing into the cache would otherwise steer what root runs. The step's
|
|
26
|
+
variables are read by the agent user's own shell, after the drop; root gets
|
|
27
|
+
only the proxy's, to install `runtime: system:` packages before that drop,
|
|
28
|
+
and touches the cache only as the agent user. The package
|
|
29
|
+
snapshots it restores carry a seal made with a key per account that no step
|
|
30
|
+
ever holds; a snapshot that does not match its seal is not restored, and even
|
|
31
|
+
a sealed one can only write package files where packages go
|
|
32
|
+
([system packages](agents#where-it-runs)).
|
|
33
|
+
|
|
20
34
|
## What the network allows
|
|
21
35
|
|
|
22
36
|
A run pod may reach DNS, the egress proxy where its credentials are filled
|
|
@@ -205,6 +219,20 @@ It holds by construction, not by care:
|
|
|
205
219
|
source of core, platform and web is scanned for any log call that prints
|
|
206
220
|
more than a literal; and metrics may only have fixed names and labels.
|
|
207
221
|
|
|
222
|
+
Each run also has one **wide event** in the platform's database (5 Nov
|
|
223
|
+
2026): when it was submitted, queued, picked up, when its first sandbox's
|
|
224
|
+
pod was ready, its tools were built and the model first answered, when it
|
|
225
|
+
finished; its runner image, size and model; what it held and used; its cost
|
|
226
|
+
and its error class. The figures the run record already has, and nothing
|
|
227
|
+
from its content — no prompt, reply, file or error text. It is what our run
|
|
228
|
+
SLOs (success rate, queue wait, pod-ready-to-first-output) are computed
|
|
229
|
+
from, and it goes with the run history (`runs.retention_days`) and with the
|
|
230
|
+
account. Its trace — the same funnel, one span per stage — goes to our
|
|
231
|
+
collector under the same rule as a log line: fixed span names, the fields
|
|
232
|
+
above in their shapes, an error as its class; the collector drops any span
|
|
233
|
+
that is not exactly that. It is not your `telemetry:` export, which sends
|
|
234
|
+
your run's own trace to your collector.
|
|
235
|
+
|
|
208
236
|
The incident this answers: a judge's model process crashed, and the full
|
|
209
237
|
text of its error — which carried prompt text — went to the server log.
|
|
210
238
|
Today that line is `model.process_failed` with `errorClass: model_error`.
|
|
@@ -227,6 +255,7 @@ an install that sets neither keeps everything, as before 5 Nov 2026.
|
|
|
227
255
|
| Your files | `storage/`, `knowledge/`, `memory/`, `state/`, your agents and flows | until you delete them | you (`foldrun storage rm`, a deploy that drops a file) |
|
|
228
256
|
| **Audit log** — security evidence | sign-ins and refusals, keys, roles, invites, secrets set or deleted (by name, never a value), deploys, exports, support access, the operator's own actions | **365 days** on the hosted platform (`audit.retention_days`; unset: kept) | the daily pass |
|
|
229
257
|
| The ledger | what each run and pod session was charged | for good — a financial record | never |
|
|
258
|
+
| A run's wide event | its funnel's timestamps, image, size, model, figures, cost and error class — metadata, never content | with run records (`runs.retention_days`) | the daily pass; closing the account |
|
|
230
259
|
| The platform's own logs and metrics | ids, counts, classes — never your content ([above](#what-our-telemetry-carries)) | as the operations stack keeps them | the operations stack |
|
|
231
260
|
|
|
232
261
|
Every period counts from when the record was written (a run: when it
|