foldrun 2.8.1 → 2.9.1

package/bin/foldrun.mjs

@@ -178,6 +178,7 @@ const HELP = `foldrun — agents are just folders
   foldrun rerun --status failed [--since 24h] [--until 2h] [--flow f]  rerun every run a filter matches, from --from <n> (default 1) — lists, asks (--dry-run, --to)
   foldrun observe           where the account fails, retries and spends, per workspace (--to <workspace> in full, --since <days>, --json)
   foldrun usage             what the account consumed, and what it was charged week by week (--days <n>, --json)
+  foldrun usage compute     the cores and GiB its running steps may hold together and in one step, and hold now (--json)
   foldrun schedule          every flow that fires on a clock, its cron line and the next times (--to <workspace>)
   foldrun schedule tick     fire whatever is due now — Settings' "Run scheduler now"
   foldrun guide             write the coding-agent rules: a block in AGENTS.md and CLAUDE.md importing it (--check, --print)

package/docs/agents.md

@@ -346,14 +346,78 @@ What holds:
 | field | |
 |---|---|
 | `size` | `small` \| `large` (default) \| `heavy` — the sandbox reservation |
+| `resources` | `{cpu, memory, disk}` in numbers, over the `size` class's figures one key at a time |
 | `runtime` | language runtimes, packages and Debian system packages the agent's own scripts need |
 
-`size` is a price, not just a limit. Memory is a **hard ceiling** because it is
-not compressible: a step over it is killed, which on a single-node host
-protects every other tenant. CPU is not capped — a step bursts to whatever is
-free and bills at its class rate. Reference figures: 1Gi, 2Gi, 8Gi. Pick
-`small` for an agent that mostly waits on an API, `heavy` for one that renders
-a browser or holds real data.
+`size` is a price and a limit. Each class gives the sandbox a number of cores,
+an amount of memory and an amount of disk, and its seconds are billed at those
+figures:
+
+| `size` | cores | memory | disk |
+|---|---|---|---|
+| `small` | 1 | 1Gi | 2Gi |
+| `large` | 2 | 2Gi | 8Gi |
+| `heavy` | 4 | 8Gi | 20Gi |
+
+These are the defaults; an install can set its own
+([environment](environment)), and the step's log says what it held.
+
+All three are **hard ceilings**:
+
+- **Memory:** a step over it is killed, because memory is not compressible.
+  On a single-node host, that protects every other tenant.
+- **Cores:** CPU is capped at the class's figure, so a step cannot take the
+  whole machine from the steps beside it. When every core is busy, a bigger
+  class gets a bigger share.
+- **Disk:** a step over it is evicted rather than the node filling up.
+  This is the step's scratch space, not the account's storage: the
+  sandbox's copy of the workspace and whatever the step writes while it
+  runs. When the step ends, the files it changed are copied back to the
+  workspace and the sandbox, scratch space included, is deleted.
+
+Pick `small` for an agent that mostly waits on an API, `heavy` for one that
+renders a browser or holds real data. The step's `resources:` line reports CPU
+busy time, **throttled** time (how long the cap held it back), and peak memory.
+A step that is throttled for much of its run wants a bigger class; one whose
+peak memory is a fraction of the class's figure can take a smaller one.
+
+### `resources:` — your own numbers
+
+When no class fits, write the numbers. Each key replaces that one figure of
+the class; the rest stay the class's:
+
+```yaml
+size: large
+resources:
+  cpu: 1          # cores, 0.5 to 8, in halves
+  memory: 6Gi     # 256Mi to 16Gi, in steps of 256Mi
+  disk: 30Gi      # whole GiB, 1Gi to 40Gi
+```
+
+Examples:
+
+- One core and a lot of memory, for an agent that loads a big CSV.
+- A lot of disk, for one that renders video.
+
+The figures are hard limits and what the step is billed at, exactly as for a
+class. The step's header on the run page shows what it held ("1 vCPU ·
+6 GiB"), with the class and your `resources:` in its tooltip.
+
+The keys are bounded and stepped the way sandbox platforms sell them, so
+steps pack onto a machine predictably. `foldrun check` reports a value
+outside them (`config/invalid-value`); at run time that one key is dropped,
+the class's figure is used, and the step's log says so. Sizes need a unit:
+`4Gi` or `512Mi`, never a bare `4`, and not `4G` (Kubernetes reads `G` as
+decimal, Docker as binary).
+
+`resources:` may also be written inside `guardrail:` ([four jobs](four-jobs)).
+When a retry moves a step up a class after it ran out of memory or disk, each
+of your figures is raised to the bigger class's, so the retry never runs
+smaller than the class it moved to.
+
+Your account's plan may also cap what one step can hold, and how much all of
+an account's running steps hold together
+([budgets and billing](budgets-and-billing)).
 
 ```yaml
 runtime:

package/docs/api.md

@@ -340,6 +340,7 @@ Reads return which secrets exist, never their values.
 | `/api/team` | GET, POST | members with their roles and workspace scope; mint an invite — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (bound into the invite: only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). Returns `path` (the invite's relative URL), `expires`, `sent` and any `sendError` either way; the full link is in the mail |
 | `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which workspaces they may open (`workspaces`: names, or null for all); remove them |
 | `/api/team/transfer` | POST | hand the account to a member (`to`) — owner only; you become an admin |
+| `/api/usage/compute` | GET | the account's compute: `compute` is `{ vcpu, memGiB, stepVcpu, stepMemGiB, source }` — the cores and GiB all its running steps may hold together, the most one step may hold (each `null` for no cap), and where the pool came from (`plan`, `account` — its own `compute:` in AGENTS.md, which can only lower it — `install`, or `null`); `inUse` is `{ vcpu, memGiB, steps }`, what its running steps' sandboxes hold now, from their records (a step still waiting for room holds nothing; a caller scoped to some workspaces sees theirs). A step past the pool waits for one of the account's steps to finish; one bigger than the pool or the step maximum fails at once ([agents](agents#resources-your-own-numbers)) |
 | `/api/usage/history?days=` | GET | charged spend by flow, by agent and by workspace over time, read from the ledger rather than the run records — so it survives runs being pruned and reports what was billed rather than what was consumed. Buckets by week over three weeks, by day under. Each series carries its periods, its total, and the change between the last two COMPLETE periods, so a partial week never reads as a collapse. `unattributedUsd` is charges from before a line recorded its flow. A caller scoped to some workspaces sees only the charges in those; `days` 1–365, default 56 |
 | `/api/account/model` | GET, PUT, DELETE | the account's own model key — what every step runs on unless an agent, workspace or the account's AGENTS.md names a `provider:`. GET: `{ set, provider, baseUrl, format, keyHint, runsOn, platformKeyAllowed }` — never the key, only its last four characters; `runsOn` is `account` (its own key), `platform` (the platform's credential, for the operator's accounts) or `none` (runs are refused until a key is set). PUT `{ provider, apiKey, baseUrl?, format? }` (needs `secrets:write`): `provider` is a preset name (anthropic, openrouter, openai, groq, … — see providers) or `custom` with an https `baseUrl` and a `format` (anthropic or openai); a Claude login token (sk-ant-oat…) is refused for any account not allowed the platform's credential. Stored as the account secrets `FOLDRUN_MODEL_PROVIDER`, `FOLDRUN_MODEL_API_KEY`, `FOLDRUN_MODEL_BASE_URL`, `FOLDRUN_MODEL_FORMAT`. DELETE removes them. Honours Idempotency-Key on PUT; audited as model.key_set / model.key_removed |
 | `/api/account/providers` | GET, POST | GET: the model providers this account's files actually use — each one's preset name, where it is declared, the model a check would send — plus the last daily health check. POST forces one now, which spends one minimal request at each distinct endpoint, and needs the permission that runs |
@@ -358,7 +359,7 @@ Reads return which secrets exist, never their values.
 | `/api/account/api` | GET, PATCH | how this account meets the API — GET `{ version: { current, pinned, effective, supported, supportMonths }, limits: { plan, windowSeconds, perCredential: { read, write }, perAccount: { read, write } }, usage }`. `usage` is the last 30 days — `{ days, versions: [{ version, requests, lastSeen }], deprecated: [{ route, requests, lastSeen, deprecatedAt, sunsetAt, link, callers: [{ credential, requests, lastSeen }] }] }`, `credential` naming a key by its label and prefix — or `null` when it could not be read; PATCH `{ version: "YYYY-MM-DD" \| null }` pins the version API-key requests without a `Foldrun-Version` header get (null: always current); the dashboard always gets current. `keys:manage`. See [api-usage](api-usage.md) |
 | `/api/account/flags` | GET | the feature flags as they stand for this account — `{ flags: [{ name, description, owner, default, on, source, rollout }] }`, `source` being what decided it: `account` (an override for this account), `global` (the install-wide setting), `rollout` (a percentage of accounts, by a stable hash of account and flag; `rollout` is the percentage) or `default`. Read-only, every role; only the super admin changes a flag. See [Feature flags](feature-flags.md) |
 | `/api/openapi.json` | GET | this API as an OpenAPI 3.1 document — every route and method, bearer auth, the rate-limit, version and Idempotency-Key headers, and request/response schemas for runs, flow runs, deploy, source, secrets, keys and billing. No key needed. Generated from the route files by `scripts/gen-openapi.mjs`; the dashboard renders it at Docs → API reference, `foldrun api spec` saves it |
-| `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place |
+| `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `compute` (`{ vcpu, memGiB }` — the account's own cap on what its running steps hold together, lower than the plan's; PATCH writes it as `compute: { vcpu, memory }`), `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place |
 | `/api/audit?since&until&action&actor&workspace&limit&cursor&format` | GET | the account's audit log, newest first — the caller's account only, whatever a header, query or body names. The owner and unscoped admins (people, or `admin` keys); `audit:read`, and refused to a member or key scoped to some workspaces, because the log is the whole account's. `since`/`until`: `7d`, `24h`, `30m` or a date; `action`: exact (`apikey.created`) or a family (`apikey`); `actor`: exact (an email, `key:<label>`, `support:<email>`); `workspace`: entries about one; `limit` 1–1000 (100; 1000 for CSV); `cursor`: the `next` of the page before. JSON `{ entries: [{ id, at, actor, action, subject, detail }], next, retention }`; `format=csv` downloads the same rows (`x-next-cursor` header when there are more). Records sign-ins and refusals, sign-outs, session revokes, password and email changes, MFA on/off, key mint/rotate/revoke, invites, joins, role/scope changes, removals, ownership transfers, secrets set/deleted (by name — never a value), deploys, workspace deletes, plan and billing changes, export and close requests, and `support.viewed`/`support.ended`. The super admin's own levers (`operator.*`) are the platform's record and not listed. Kept for the life of the account |
 | `/api/avatars/<kind>/<id>` | GET, PUT, DELETE | a picture for a `user` (their own id), a `workspace` (its name) or the `account` (the tenant). PUT the bytes of a PNG, JPEG or WebP under 1 MB; a person sets their own, an admin a workspace's or the account's. GET needs a signed-in tenant and is privately cached for a year — the URL's `?v=` changes with the picture |
 | `/api/search?q=` | GET | find anything in the account by name — workspaces, agents, flows, tools, skills, knowledge, memory, runs (by id, flow or headline); ranked, at most six per kind. The dashboard's Find palette reads it |
@@ -427,7 +428,7 @@ X-Foldrun-Cli: 0.6.0               # the CLI released with this version (absent
 
 | Route | Methods | |
 |---|---|---|
-| `/api/auth/signup` | POST | `email`, `password`, `account`, `invite`. Rate limited per address and per caller. With signups closed every address gets the same refusal, so the form cannot be used to discover which addresses are registered |
+| `/api/auth/signup` | POST | `email`, `password`, `account`, `invite`, `setup`. An install with `FOLDRUN_SETUP_TOKEN` set creates its first account only with `setup` equal to it (403 otherwise); once an account exists the token does nothing. Rate limited per address and per caller. With signups closed every address gets the same refusal, so the form cannot be used to discover which addresses are registered |
 | `/api/auth/login` | POST | `email`, `password` |
 | `/api/auth/logout` | POST | ends the session |
 | `/api/auth/session` | GET | who am I |

package/docs/budgets-and-billing.md

@@ -27,6 +27,7 @@ wins, and the step's error says which line set it: `budget: in the flow
 file` or `budget: on the writer agent`.
 | **runs at once** | `concurrency: 3` in the account's `AGENTS.md`, or Settings → Governance | the fourth run waits its turn in the queue — never refused, only later. Empty means the install's share (`FOLDRUN_ACCOUNT_CONCURRENCY`) or plan number (`FOLDRUN_PLAN_CONCURRENCY`, which applies only where billing is on), or no cap. Your own number can lower that, never raise it; a higher number comes with a plan |
 | **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 |
+| **compute at once** | the plan's cores and GiB (below); `compute: { vcpu: 4, memory: 8Gi }` in the account's `AGENTS.md`, or Settings → Governance, lowers it | what all the account's running steps may hold together — each step's cores and memory, 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 when one of the account's steps ends. 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`, 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 |
 | **room to start** | the install's `FOLDRUN_RUN_MEMORY_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; the run page's start-up chip shows it as `room`. A step still waiting after 30 minutes (`FOLDRUN_ROOM_WAIT_SEC`) fails, saying why |
 
 A cap is a literal, never an expression, so it is readable off the file. The
@@ -64,12 +65,18 @@ at the platform's rates. The ledger stays in dollars underneath — every
 statement, budget and refund reconciles to one column — and a credit is how
 the money is shown and bought.
 
-| plan | a month | credits a month | an extra credit | runs at once | workspaces | queue lane |
-|---|---|---|---|---|---|---|
-| **Starter** | $29 | 2,900 | 1.00¢ | 1 | 3 | standard |
-| **Creator** | $79 | 8,800 | 0.90¢ | 2 | 10 | standard |
-| **Pro** | $249 | 29,000 | 0.86¢ | 4 | unlimited | fast |
-| **Scale** | $799 | 100,000 | 0.80¢ | 8 | unlimited | fast |
+| plan | a month | credits a month | an extra credit | runs at once | compute at once | one step, at most | workspaces | queue lane |
+|---|---|---|---|---|---|---|---|---|
+| **Starter** | $29 | 2,900 | 1.00¢ | 1 | 4 vCPU · 8 GiB | 4 vCPU · 8 GiB | 3 | standard |
+| **Creator** | $79 | 8,800 | 0.90¢ | 2 | 8 vCPU · 16 GiB | 4 vCPU · 8 GiB | 10 | standard |
+| **Pro** | $249 | 29,000 | 0.86¢ | 4 | 16 vCPU · 32 GiB | 8 vCPU · 16 GiB | unlimited | fast |
+| **Scale** | $799 | 100,000 | 0.80¢ | 8 | 32 vCPU · 64 GiB | 8 vCPU · 16 GiB | unlimited | fast |
+
+**Compute at once** is what all of an account's running steps may hold
+together, counted by the cores and memory each step's sandbox is capped at.
+**One step, at most** is the largest single step the plan runs: `heavy`
+(4 vCPU · 8 GiB) on every plan, and up to 8 vCPU · 16 GiB with `resources:`
+on Pro and Scale.
 
 **How long a credit lasts.** A plan's credits land when its invoice is paid,
 and what is unused **rolls over** into the next cycle up to **twice** the

package/docs/four-jobs.md

@@ -37,8 +37,8 @@ top. Either way works, and the two can be mixed in one file.
 
 | File | `governance:` | `guardrail:` | `observability:` | `evaluation:` |
 |---|---|---|---|---|
-| `AGENTS.md` | `owner`, `budget`, `priority`, `concurrency`, `deploy_block` | `limits`, `network`, `network_enforce`, `hooks` | `alerts`, `telemetry`, `notify`, `capture` | `judge` |
-| an agent | `owner`, `budget` | `limits`, `network`, `hooks`, `disallowedTools`, `permissionMode`, `secrets`, `sandbox` | — | — |
+| `AGENTS.md` | `owner`, `budget`, `priority`, `concurrency`, `compute`, `deploy_block` | `limits`, `network`, `network_enforce`, `hooks` | `alerts`, `telemetry`, `notify`, `capture` | `judge` |
+| an agent | `owner`, `budget` | `limits`, `network`, `hooks`, `disallowedTools`, `permissionMode`, `secrets`, `sandbox`, `resources` | — | — |
 | a flow | `owner`, `approvers`, `approve_within`, `budget`, `priority` | `throttle`, `debounce`, `overlap`, `disable_after`, `live` | `issues`, `sla` | — |
 
 A field that does none of the four, such as `name`, `model`, `tools`,

package/docs/self-hosting.md

@@ -23,36 +23,146 @@ A self-hosted server has no billing: nothing is charged, and spend budgets
 
 ## Your own server
 
-One machine with Docker. The platform runs in one container — the dashboard,
-the API, the scheduler and the queue — and every agent step runs in a
-throwaway container beside it, started through the Docker socket.
+One machine with Docker — Linux or macOS, Intel/AMD (amd64) or ARM (arm64);
+on Windows, inside WSL2 with Docker Desktop's WSL integration. One command:
 
 ```sh
-mkdir foldrun && cd foldrun
-for r in foldrun-core foldrun-platform foldrun-web foldrun-docs; do
-  git clone https://github.com/foldrun-io/$r
-done
-cd foldrun-web/self-hosting
-echo "FOLDRUN_SECRET_KEY=$(openssl rand -hex 32)" > .env
-echo "FOLDRUN_PUBLIC_URL=http://<host>:3900" >> .env   # the address people open
-docker compose up -d --build
+curl -fsSL https://foldrun.io/install.sh | sh
 ```
 
-Then open `http://<host>:3900/signup` (the first account needs no flag),
-sign the CLI in to it, and deploy an account folder:
+It checks Docker, puts `docker-compose.yml` in `~/foldrun`, writes `.env`
+there once (a fresh secret key, the address, the version), pulls the
+ready-made images for your machine's chip and starts foldrun on port 3900.
+
+**No Docker yet?** The installer offers to set it up, and asks before each
+step (`[y/N]`):
+
+| on | Docker missing | Docker stopped | Docker not reachable by you |
+|---|---|---|---|
+| **macOS** | installs Colima (a small Linux VM), `docker` and `docker-compose` with [Homebrew](https://brew.sh), then starts Colima with up to 4 CPUs and 8 GiB — enough for a `heavy` step | starts Colima, or opens Docker Desktop | — |
+| **Linux** | runs Docker's official script ([get.docker.com](https://get.docker.com): the engine and the Compose plugin) as root, through `sudo` | `sudo systemctl start docker` | adds you to the `docker` group (root-equivalent), and uses `sudo` for the rest of that run; the group applies from your next login |
+
+Answer after each question appears: anything typed ahead is lost while
+Docker installs.
+
+**What it checks first.** The install folder and every file Compose reads
+there (`.env`, `docker-compose.yml`, `docker-compose.override.yml`) must be
+yours alone — owned by you, writable by nobody else, no access control list,
+no symlinks — because Docker runs what they say with root's reach. The
+override must stand alone: no `include` or `extends`, and no `env_file` —
+put settings in `.env` or in the override's own `environment:`. Anything
+else it names, such as a secret's file, is your own configuration to
+protect, as is a key written to slip past these checks.
+
+`FOLDRUN_DATA_DIR` (a host folder instead of the data volume) holds the
+accounts and the vault, so it must be private: the installer makes it
+owner-only when it does not exist, refuses one that others can read or
+write, and keeps its real path (symlinks resolved) in `.env`.
+
+The installer sets foldrun up on the machine it runs on, and refuses a
+remote Docker (`DOCKER_HOST` or a context pointing at another machine): run
+it on the Docker host itself.
+Compose is always given these files by name, so a `compose.yaml` beside them
+or a `COMPOSE_FILE` in `.env` cannot stand in. Before starting, it checks
+that the Docker the platform will be given (`FOLDRUN_DOCKER_SOCK`) is the
+same daemon it installed into. With no terminal (a provisioning script), nothing is
+installed unless you say so in advance with `FOLDRUN_INSTALL_DOCKER=yes`;
+`FOLDRUN_INSTALL_DOCKER=no` never asks. Without Homebrew on a Mac, install
+it or [Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/)
+first. Then open the signup link it prints —
+`http://127.0.0.1:3900/signup?setup=…` (127.0.0.1, not `localhost`, which a browser may send to IPv6 where another user could be listening) — in a browser. The first account
+becomes the owner, and only that link can create it: anyone else using the
+same machine can reach `localhost` too, so the installer ties the owner to
+whoever ran it (the token is `FOLDRUN_SETUP_TOKEN` in `~/foldrun/.env`, and
+does nothing once the owner exists). With `FOLDRUN_BIND` set to one address
+the link uses that address; from another machine, open it through the
+tunnel the installer prints (`ssh -o ExitOnForwardFailure=yes -L …`), never
+over plain http. Then sign the CLI in and deploy:
 
 ```sh
 npm install -g foldrun
-foldrun login --url http://<host>:3900   # approve in the browser; or --token <a key from Settings>
-foldrun deploy                           # from the account folder
+foldrun login --url http://localhost:3900
+foldrun deploy                           # from your account folder
 ```
 
-`docker-compose.yml` beside the Dockerfile lists every setting with what it
-does: the install's model key (or none, and each account brings its own),
-open sign-up (off), retention. `FOLDRUN_PUBLIC_URL` is required: CLI sign-in,
-approve links, password resets and shares are made with it, so it must be
-the address people actually open. Back up the `foldrun-data` volume and `FOLDRUN_SECRET_KEY` and
-you have backed the install up.
+To read the script before it runs (anything piped into a shell deserves it):
+`curl -fsSL https://foldrun.io/install.sh -o install.sh`, read it, then
+`sh install.sh`. Its source is `self-hosting/install.sh` in
+[foldrun-web](https://github.com/foldrun-io/foldrun-web/tree/main/self-hosting).
+
+The platform runs in one container — the dashboard, the API, the scheduler
+and the queue — and every agent step runs in a throwaway container beside
+it, started through the Docker socket. The images are
+`ghcr.io/foldrun-io/platform` and `ghcr.io/foldrun-io/runner`, public, built
+from these repositories.
+
+### Settings
+
+Give them to the installer as environment variables
+(`curl -fsSL https://foldrun.io/install.sh | FOLDRUN_BIND=0.0.0.0 sh`) or
+edit `~/foldrun/.env` and run `docker compose up -d` there.
+
+| variable | default | what |
+|---|---|---|
+| `FOLDRUN_PUBLIC_URL` | `http://localhost:3900` | the address people open. CLI sign-in, approve links, password resets and shares are made with it |
+| `FOLDRUN_BIND` | `127.0.0.1` | where the dashboard listens. The default is this machine only — reach it over an SSH tunnel or a reverse proxy. `0.0.0.0` opens it to the network: sign up straight away, because the first account becomes the owner |
+| `FOLDRUN_VERSION` | the current `stable` | a version to pin, `vYYYY.MM.DD.N`; `stable` unpins. Give it to the installer: in `.env` by hand it holds only with `FOLDRUN_PINNED=yes` beside it, or the next installer run moves it to `stable` |
+| `ANTHROPIC_API_KEY` | none | the install's model key. Without one, each account adds its own in Settings → Model; a step with neither is refused with what to set |
+| `FOLDRUN_DIR` | `~/foldrun` | where the install lives (installer only) |
+| `FOLDRUN_DOCKER_SOCK` | `/var/run/docker.sock` | the Docker socket; rootless Docker is found by the installer |
+| `FOLDRUN_SETUP_TOKEN` | made once | the first account (the owner) is created only with this, through the printed `/signup?setup=…` link |
+| `FOLDRUN_INSTALL_DOCKER` | ask | `yes` installs or starts Docker without asking (for a script with no terminal); `no` never offers to |
+| `FOLDRUN_EGRESS_BIND` | `0.0.0.0` | the egress proxy's port 8090, which steps reach through `host.docker.internal`. On a server that faces a network, bind it to the Docker bridge (`172.17.0.1`); Docker-published ports skip host firewalls such as ufw |
+| `FOLDRUN_DATA_DIR` | a named volume | a host path for the data instead |
+
+`docker-compose.yml` lists the rest (concurrency, retention, gVisor, other
+model endpoints). Put your own changes in `docker-compose.override.yml`
+beside it, which Compose reads too: the installer replaces
+`docker-compose.yml` on an update and keeps a copy of one you edited.
+
+### Updating, versions, both kinds of chip
+
+Run the installer again. It keeps `.env` (the secret key, your settings),
+moves `FOLDRUN_VERSION` to the newest `stable`, pulls and restarts; your
+data stays in its volume. With a version pinned, a re-run keeps it.
+
+`stable` is the newest version built for both amd64 and arm64, so the same
+command works on an Intel server and an Apple Silicon Mac. It moves forward
+once a day at most; each version is tested on foldrun's own servers first.
+
+### Backups
+
+`~/foldrun/.env` (the secret key: losing it signs everyone out and voids
+every webhook URL) and the data volume (`foldrun_foldrun-data`, or your
+`FOLDRUN_DATA_DIR`) are the whole install. Stop with `docker compose stop`;
+`docker compose down -v` deletes the data volume.
+
+### By hand, or from source
+
+The installer is a convenience. The same by hand:
+
+```sh
+mkdir ~/foldrun && cd ~/foldrun
+curl -fsSLO https://raw.githubusercontent.com/foldrun-io/foldrun-web/main/self-hosting/docker-compose.yml
+echo "FOLDRUN_SECRET_KEY=$(openssl rand -hex 32)" > .env
+echo "FOLDRUN_PUBLIC_URL=http://localhost:3900" >> .env
+echo "FOLDRUN_BIND=127.0.0.1" >> .env      # this machine only, as the installer does
+docker compose up -d
+```
+
+From source instead of images — the four repositories side by side, built
+here (a few minutes and some gigabytes the first time):
+
+```sh
+for r in foldrun-core foldrun-platform foldrun-web foldrun-docs; do
+  git clone https://github.com/foldrun-io/$r
+done
+cd foldrun-web/self-hosting
+echo "FOLDRUN_SECRET_KEY=$(openssl rand -hex 32)" > .env
+echo "FOLDRUN_PUBLIC_URL=http://localhost:3900" >> .env
+echo "FOLDRUN_BIND=127.0.0.1" >> .env
+docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
+```
 
 ## Your machine
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "2.8.1",
+  "version": "2.9.1",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "FSL-1.1-ALv2",
   "type": "module",
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^2.12.1"
+    "@foldrun/core": "^2.13.0"
   },
   "files": [
     "bin",

package/src/commands.mjs

@@ -5650,6 +5650,7 @@ function printDefaults(d) {
   console.log(`  notify       ${notify}`);
   console.log(`  budget       ${d.budget ? `$${d.budget.usd} per ${d.budget.period}` : c.dim("no cap")}`);
   console.log(`  concurrency  ${d.concurrency ?? c.dim("the plan's number")}`);
+  console.log(`  compute      ${d.compute ? `${d.compute.vcpu ?? "plan's"} vCPU · ${d.compute.memGiB ?? "plan's"} GiB ${c.dim("— at most, for all running steps")}` : c.dim("the plan's (foldrun usage compute)")}`);
   console.log(`  deploy_block ${d.deployBlock && d.deployBlock !== "none" ? `${d.deployBlock} ${c.dim(d.deployBlock === "secrets" ? "— a written-in key refuses a deploy" : "— any security finding refuses a deploy")}` : c.dim("none — security findings only warn")}`);
   console.log(`  network      ${networkEnforceText(d.networkEnforce, "the install")}`);
 }
@@ -5951,7 +5952,7 @@ async function accountCmd(positional, flags) {
   if (key === "telemetry" && verb === "set") {
     throw new Error("telemetry has its own verb — `foldrun account telemetry set <otlp-url> [--header name=value]`; `foldrun account clear telemetry` turns it off");
   }
-  const KEYS = ["timezone", "notify", "budget", "concurrency", "deploy_block", "network_enforce", "owner", "alerts", "judge", ...(verb === "clear" ? ["telemetry"] : [])];
+  const KEYS = ["timezone", "notify", "budget", "concurrency", "compute", "deploy_block", "network_enforce", "owner", "alerts", "judge", ...(verb === "clear" ? ["telemetry"] : [])];
   if (!KEYS.includes(key)) {
     throw new Error(`which setting? \`foldrun account ${verb} <${KEYS.join("|")}> …\` — or <job>.<field>, e.g. governance.owner (\`foldrun jobs\` lists them)`);
   }
@@ -5961,6 +5962,20 @@ async function accountCmd(positional, flags) {
     patch = { [key]: null };
   } else if (key === "alerts" || key === "judge") {
     patch = { [key]: await mergedEntry(url, flags, key, positional.slice(2), null, view, `foldrun account set ${key}`) };
+  } else if (key === "compute") {
+    // `set compute vcpu 4 memory 8` (GiB) — either or both, over what is set.
+    const pairs = positional.slice(2);
+    const usage = "`foldrun account set compute vcpu <cores> memory <GiB>` — either or both";
+    if (!pairs.length || pairs.length % 2) throw new Error(usage);
+    const { defaults } = await remoteCall(url, flags, "/api/account");
+    const next = { vcpu: defaults?.compute?.vcpu ?? null, memGiB: defaults?.compute?.memGiB ?? null };
+    for (let i = 0; i < pairs.length; i += 2) {
+      const [k, v] = [pairs[i], pairs[i + 1]];
+      if (k !== "vcpu" && k !== "memory") throw new Error(`${usage} — not "${k}"`);
+      if (!/^\d+(\.\d+)?$/.test(v)) throw new Error(`compute ${k} is a number${k === "memory" ? " of GiB" : " of cores"} — not "${v}"`);
+      next[k === "vcpu" ? "vcpu" : "memGiB"] = Number(v);
+    }
+    patch = { compute: next };
   } else if (key === "notify") {
     // `set notify email you@example.com` / `set notify url https://…`, and
     // --events to change what is notified on.
@@ -9612,6 +9627,29 @@ async function usageCmd(flags) {
   return 0;
 }
 
+/**
+ * `foldrun usage compute` — the cores and GiB the account's running steps
+ * may hold together and in one step, and what they hold now (Settings →
+ * Governance, GET /api/usage/compute).
+ */
+async function usageComputeCmd(flags) {
+  const url = platformFor(flags, "usage compute");
+  const d = await remoteCall(url, flags, "/api/usage/compute");
+  if (flags.json === true) {
+    console.log(JSON.stringify(d, null, 2));
+    return 0;
+  }
+  const p = d.compute ?? {};
+  const u = d.inUse ?? { vcpu: 0, memGiB: 0, steps: 0 };
+  const of = (used, cap, unit) => (cap == null ? `${used} ${unit} ${c.dim("(no cap)")}` : `${used} of ${cap} ${unit}`);
+  const from = { plan: "the plan's", account: "the account's own compute:", install: "this install's" }[p.source] ?? null;
+  console.log(`\n  ${c.bold("compute")}  ${c.dim(from ? `${from} — what all running steps may hold together` : "no pool set")}`);
+  console.log(`  ${of(u.vcpu, p.vcpu, "vCPU")} · ${of(u.memGiB, p.memGiB, "GiB")}  ${c.dim(`held by ${u.steps} running step${u.steps === 1 ? "" : "s"}`)}`);
+  if (p.stepVcpu != null || p.stepMemGiB != null) console.log(`  ${c.dim(`one step: up to ${p.stepVcpu ?? "any"} vCPU · ${p.stepMemGiB ?? "any"} GiB`)}`);
+  console.log(`\n  ${c.dim("a step past the pool waits for one to finish · lower it: foldrun account set compute vcpu <n> memory <GiB>")}\n`);
+  return 0;
+}
+
 /** `foldrun billing <verb>` — statement, wallet, details, portal; bare, the balance. */
 async function billingVerbCmd(positional, flags) {
   const url = platformFor(flags, "billing");
@@ -11778,6 +11816,7 @@ export async function run(command, positional, flags, workspace, layout) {
     case "observe":
       return observeCmd(flags, layout);
     case "usage":
+      if (positional[0] === "compute") return usageComputeCmd(flags);
       return usageCmd(flags);
     case "workspace":
       if (positional[0] === "vocabulary") return vocabularyCmd(flags, layout);

package/src/guide.mjs

@@ -30,7 +30,7 @@ export function agentRulesBlock() {
 
 # Read foldrun's docs before you edit this folder
 
-This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply and the files it wrote reach the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value. A webhook, email, chained or storage flow says which deliveries start it with \`filter:\` (\`foldrun flow filter <flow> --payload body.json\` tries one); an eval with \`trigger: runs\` grades a \`sample:\` of real finished runs instead of running cases, \`foldrun eval compare\` runs an eval's cases under several models side by side, and \`improve: true\` turns repeated failures into a proposed fix a person applies (\`foldrun docs evals\`).
+This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply and the files it wrote reach the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value. What a step's sandbox may use is \`size:\` (\`small\` 1 core/1Gi, \`large\`, \`heavy\` 4 cores/8Gi — hard limits and the billed figures); \`resources: {cpu, memory, disk}\` sets the numbers yourself, key by key over the class (\`foldrun docs agents\`). A webhook, email, chained or storage flow says which deliveries start it with \`filter:\` (\`foldrun flow filter <flow> --payload body.json\` tries one); an eval with \`trigger: runs\` grades a \`sample:\` of real finished runs instead of running cases, \`foldrun eval compare\` runs an eval's cases under several models side by side, and \`improve: true\` turns repeated failures into a proposed fix a person applies (\`foldrun docs evals\`).
 
 This block is for coding tools. It is written and re-added by the foldrun CLI, and the runtime strips it, so the agents that run here never see it; the rest of this file is the account's own context, which they do read. Committing the block with your work keeps the tree clean.