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 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. On a laptop (`foldrun run` with no container) there is nothing to
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 uses the same cache
589
- and snapshots as `runtime: system:`, so a package anyone in the account
590
- installed before is back in about a second. pip and npm packages need no root
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 DNS and
131
- nothing else, so a program that ignores the proxy variables finds no route
132
- instead of going round the list; it cannot reach the account's browser or
133
- search pods either, which are the world fetched on a run's behalf.
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 only.
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 DNS, and the browser runs
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) and DNS, so a page, a script or a changed proxy setting reaches no site off the list; DNS lookups themselves are not restricted.
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 through the cluster's resolver (the wall admits
226
- DNS, and nothing restricts the names asked), WebSocket upgrades to a host a
227
- secret is granted to (they fail), and — as for every tunnel — which origins
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "17.1.0",
3
+ "version": "17.1.2",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",