foldrun 20.5.3 → 20.7.0
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 +4 -1
- package/docs/a2a.md +1 -1
- package/docs/api.md +4 -5
- package/docs/checks.md +2 -1
- package/docs/cli.md +1 -3
- package/docs/mcp.md +2 -2
- package/package.json +2 -2
- package/src/commands.mjs +223 -4
- package/docs/claude-code.md +0 -180
package/bin/foldrun.mjs
CHANGED
|
@@ -258,6 +258,7 @@ const HELP = `foldrun — agents are just folders
|
|
|
258
258
|
foldrun pull [workspace] bring the platform's account down here (refuses to clobber; --force overrides)
|
|
259
259
|
foldrun export [workspace] a deployed workspace as a .zip — agents, flows, tools, skills, scripts, evals, knowledge; never memory, state or secret values (--flow <name> or --agent <name> for one, with what it needs; --file <path>|-, --force)
|
|
260
260
|
foldrun import <file.zip> take a package in: shows what it adds, would replace and still needs, then asks (--to <workspace>; a new name makes a workspace; --dry-run, --overwrite, --yes, --json)
|
|
261
|
+
foldrun snapshot push [dir] send a git folder for an agent on foldrun to work on: what git would commit, checked for secrets here and on the platform, answers the snapshot id (--to <workspace>; --dry-run, --out <file.tar.gz> (--force over one that is there), --json)
|
|
261
262
|
foldrun status [workspace] per workspace: what is added, changed or gone since the last deploy
|
|
262
263
|
foldrun status --platform is the platform up: each component, and any incident or maintenance posted (--json)
|
|
263
264
|
foldrun status --platform --history uptime per component per day and the incidents in the window, as the status page's bars (--days 1-90, default 90; --json)
|
|
@@ -306,6 +307,7 @@ Signing in
|
|
|
306
307
|
foldrun keys create <label> --a2a --to <ws> --flows a,b a key for an OUTSIDE agent: it opens /a2a for those published flows and no /api route (--max-tasks N open at once, default 10; --expires); shown once
|
|
307
308
|
foldrun keys set <id> --sonnet openai/gpt-6 which model a gateway key runs each Claude Code tier on (--opus, --haiku; - clears one, --clear all)
|
|
308
309
|
foldrun keys create <label> --gateway --cap <usd> [--daily <usd>] a key for a CODING agent (Claude Code: ANTHROPIC_BASE_URL + this key) — it spends the account's credits on foldrun's models through the gateway, up to its own limits, and opens no /api route; an admin of every workspace; shown once
|
|
310
|
+
foldrun keys create laptop --gateway --cap 20 --claude-code the same, and Claude Code is set up on this machine: the URL and key go into its settings
|
|
309
311
|
foldrun a2a ls --to <ws> what a workspace serves over A2A: each flow's a2a:, card and endpoint URLs, its A2A keys (admins), recent tasks and the key that asked (--json)
|
|
310
312
|
foldrun a2a publish <flow> set a2a: publish: true in the flow (--to <ws>: the deployed copy, an admin's) — --name, --description, --example "…" (repeatable), --public-card | --private-card; diff, checked, --dry-run
|
|
311
313
|
foldrun a2a publish <flow> --clear-name | --clear-description | --clear-examples drop the card's name, description or examples (also on unpublish)
|
|
@@ -457,6 +459,7 @@ Options
|
|
|
457
459
|
--gateway keys create: a gateway key for Claude Code — with --cap <usd> (in all) and/or --daily <usd> (per UTC day)
|
|
458
460
|
--cap <usd>, --daily <usd> keys create --gateway: the key's own spending limits, $0.01–$100000
|
|
459
461
|
--login keys create --gateway: on the operator's Claude login instead (the operator's own accounts; not metered, no limits)
|
|
462
|
+
--claude-code keys create --gateway: also write the gateway URL and the key into Claude Code's settings (~/.claude/settings.json, or $CLAUDE_CONFIG_DIR) — nothing to copy
|
|
460
463
|
--opus, --sonnet, --haiku <model> keys set <id>: which model that Claude Code tier runs on with a gateway key (e.g. openai/gpt-6; - clears it)
|
|
461
464
|
--key-env <NAME> a2a call, a2a status, a2a cancel, a2a card: the environment variable holding the A2A key (default FOLDRUN_A2A_KEY) — a key is never taken on the command line
|
|
462
465
|
--card <url> a2a status, a2a cancel: the agent card of the agent that holds the task
|
|
@@ -502,7 +505,7 @@ if (!command || command === "--help" || command === "-h") {
|
|
|
502
505
|
// `--value` as the account's argument and stored an empty secret; `--force
|
|
503
506
|
// ./dir` swallowed the directory. A flag followed by another flag is also
|
|
504
507
|
// boolean, so an unlisted switch at least does not eat its neighbour.
|
|
505
|
-
const BOOLEAN_FLAGS = new Set(["read-only", "account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "generate-key", "device", "write", "dpop", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "gateway", "login", "unreachable", "public-card", "private-card", "return-immediately", "online", "overwrite", "no-send", "event-wait", "with-client", "use", "clear-name", "clear-description", "clear-examples", "clear-accept-risk", "clear-address", "clear-email", "clear-abn", "no-task", "empty"]);
|
|
508
|
+
const BOOLEAN_FLAGS = new Set(["read-only", "account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "generate-key", "device", "write", "dpop", "export", "isolated", "no-wait", "dismissed", "unread", "team", "started", "mine", "none", "a2a", "gateway", "claude-code", "login", "unreachable", "public-card", "private-card", "return-immediately", "online", "overwrite", "no-send", "event-wait", "with-client", "use", "clear-name", "clear-description", "clear-examples", "clear-accept-risk", "clear-address", "clear-email", "clear-abn", "no-task", "empty"]);
|
|
506
509
|
// Flags said more than once collect into a list: `--tag a --tag b`.
|
|
507
510
|
const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param", "example", "accept-risk"]);
|
|
508
511
|
// `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
|
package/docs/a2a.md
CHANGED
|
@@ -198,7 +198,7 @@ the flow's page and `foldrun a2a card` show them whole.
|
|
|
198
198
|
| `POST /a2a/<account>/<ws>/flows/<flow>` | the JSON-RPC endpoint |
|
|
199
199
|
| `GET /a2a/<account>/<ws>` | the flows this key may call here, each with its card and endpoint — a convenience index, not an A2A operation |
|
|
200
200
|
|
|
201
|
-
Every call sends the key as `Authorization: Bearer
|
|
201
|
+
Every call sends the key as `Authorization: Bearer fr_a2a_…` and the protocol
|
|
202
202
|
version as `A2A-Version: 1.0` (or `?A2A-Version=1.0`). A request without the
|
|
203
203
|
header is A2A 0.3, which is not served: it is answered
|
|
204
204
|
`VersionNotSupportedError` (`-32009`). A session cookie never opens `/a2a`.
|
package/docs/api.md
CHANGED
|
@@ -199,7 +199,7 @@ history with each message.
|
|
|
199
199
|
|---|---|---|
|
|
200
200
|
| `/api/workspaces/<ws>/agents` | GET, POST | list — each agent's frontmatter as read, `owner` and `ownerFrom` (its own `owner:`, else the workspace's, else the account's), `lastRunAt` (when its latest step that ran started, from the runs kept; null for none) and `stale` (past `alerts: stale_days`); create (`name`) |
|
|
201
201
|
| `/api/workspaces/<ws>/agents/<agent>` | PATCH | edit one line of an agent's frontmatter in place, as the flow canvas does: `{ list: { key, name, action } }` — `key` one of `subagents`, `agents`, `tools`; `action` `add` or `remove` — or `{ set: { key: "description" | "sandbox", value } }` (`sandbox` takes `own` or `parent`, else 400), or `{ network }` — the sites its sandbox may reach: `"open"`, `"trusted"`, `"none"`, a list of sites, or `{ level, allow, defaults }`; `null` removes the line so it inherits ([Network](network)). A `network` nobody could read is a 400 that says why. Only that key's lines change — comments, key order and prose stay. Answers `{ ok, changed }`; 404 for an unknown agent. `workspace:write` |
|
|
202
|
-
| `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run) |
|
|
202
|
+
| `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run; `snapshot`: a folder to work on, the id `POST …/snapshots` answered — the step finds it in `snapshot/`, only its `outputs/` come back to the workspace, and the run's outputs hold `snapshot.patch`, the change as a git patch, with `snapshot.json` saying what it touched or why there is none. Needs the k8s sandbox: `409` on an install without it, `404` for a snapshot not in this workspace) |
|
|
203
203
|
| `/api/workspaces/<ws>/agents/import` | GET, POST | copy an agent in from another workspace of the account. GET lists what could be imported (every other workspace you can read, with its agents). POST `{ from, agent, as? }` copies `agents/<agent>/` — its agent.md and own skills/, scripts/, knowledge/; never memory/, outputs/, state/ — and answers `{ name, files, warnings }`; `warnings` names tools, skills, scripts and secrets the copy uses that this workspace lacks. 409 on a name clash (pass `as`), 404 for an unknown workspace or agent, 403 when `from` is outside your key's scope. Idempotent |
|
|
204
204
|
| `/api/workspaces/<ws>/proposals` | GET | the workspace's proposed fixes, newest first (`404` when the workspace does not exist): `{ proposals: [{ id, workspace, eval, by (auto, or who asked), createdAt, updatedAt, status, failures: [{ runId?, case?, check, detail, at }], jobId, reply (the assistant's reasoning), files: [{ path, content, before, sha256 }], issues: [{ where, message, level }], error?, notes?, decidedBy?, decidedAt?, applied? }] }`. `status` is `drafting`, `ready`, `failed`, `applying`, `applied`, `partial` (a write failed part-way; `applied` names what was written) or `dismissed`. `?status=`, `?eval=`. A drafting one is settled as it is read |
|
|
205
205
|
| `/api/workspaces/<ws>/proposals/<id>` | GET, POST | one proposal. `POST { action: "apply" }` writes its files, each a revision by the caller, only when every one still reads what it was drawn against (`409` naming the file that changed) and can be written (`422`; a check error the deploy would refuse is `422` too); `POST { action: "dismiss" }` sets it aside — its failures stay looked at. Only agents, flows and skills are ever in one. Needs `workspace:write` |
|
|
@@ -367,8 +367,7 @@ Reads return which secrets exist, never their values.
|
|
|
367
367
|
|
|
368
368
|
| Route | Methods | |
|
|
369
369
|
|---|---|---|
|
|
370
|
-
| `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must say `a2a: { publish: true }` when the key is minted — a flow not published is refused, 400 — and still say it on every call) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, and the key is shown once.
|
|
371
|
-
| `/api/keys/<id>` | PATCH | a gateway key's model map: `{ models: { opus?, sonnet?, haiku? } }` — which model each Claude Code tier runs on with that key (`provider/model` such as `openai/gpt-6`, or a known prefix), each on foldrun's price list; a login gateway key maps to Claude models only; `{ models: null }` clears it. Answers `{ ok, id, models }`. `keys:manage` and an admin of every workspace; any other key is 400. The gateway reads the change within its 10 s key cache. Audited as `apikey.models`. The same `models` may be given when minting (`POST /api/keys { purpose: "gateway", models }`) |
|
|
370
|
+
| `/api/keys` | GET, POST, DELETE | API keys — an admin's (`keys:manage`) to list, mint and revoke; any key may revoke itself (DELETE with its own `id`, audited as self — what `foldrun logout` does). POST `label`, `role` (viewer \| editor \| admin, never above your own, default editor), `workspaces` (names, or `null` for all — never wider than your own scope); `expires` (`30d`, `90d`, `365d`, any number of days up to 3650, or `never` — the default; anything else is a 400, never a key that lives forever); returns `{ ok, key, id, prefix, role, workspaces, expiresAt }`. A key's prefix says what it is: `fr_api_` an API key, `fr_a2a_` an A2A key (`fr_dep_` is reserved for deploy keys); keys minted before 11 Nov 2026 start `mda_` (or `mdk_`) and keep working — a key is looked up by its hash, never its prefix, and `prefix` is its first 12 characters. POST `{ purpose: "a2a", workspace, flows, maxTasks?, label?, expires? }` mints an A2A key instead: for an outside agent, it opens `/a2a/<account>/<workspace>/…` for the named flows (each must say `a2a: { publish: true }` when the key is minted — a flow not published is refused, 400 — and still say it on every call) and every `/api` route refuses it (403); `maxTasks` (1–100, default 10) caps its tasks open at once; it answers `{ ok, key, id, prefix, purpose, workspace, flows, maxTasks, role, workspaces, expiresAt }`, and rotating one keeps the tasks it made, and the key is shown once. GET lists each key with `createdAt`, `createdBy`, `expiresAt`, `lastUsedAt`, `lastIp` and `replacedBy` (the id of the key a rotation replaced it with; `null` until then) — the last-use pair written at most once a minute per key, the address cut to its /24 (IPv4) or /48 (IPv6). A key past its `expiresAt` is refused with 401 `API key expired on <date>`; the owner is emailed seven days before. Mint, revoke and rotate are written to the audit log. POST with `workspace` or `access` is refused (400): those minted deploy keys for the platform's own git, which went on 17 Oct 2026 — a deploy key minted before is refused everywhere (403). A key for one workspace is `workspaces: ["<ws>"]`. DELETE `id`. `?tenant=` / body `tenant` is read only on an install with no users yet (first-run bootstrap), and there, when the install has a setup token (`FOLDRUN_SETUP_TOKEN`, written by the self-hosting installer), only with that token in `X-Foldrun-Setup-Token` |
|
|
372
371
|
| `/api/keys/<id>/rotate` | POST | a new key with the old one's label, role, workspaces and deploy scope — and, when it had an end, the same lifetime from today — returned once like a mint (`{ ok, key, id, prefix, role, workspaces, expiresAt, replaced: { id, endsAt } }`). `grace`: `0` (default — the old key is revoked at once), or a duration up to `7d` such as `1h` or `24h`, during which the old key still works and after which it is refused as expired. A key is rotated once: rotating a key already replaced is 409 `this key was already rotated to <prefix>…; rotate that one` — and someone who lost the new key's secret rotates the NEW key, which mints another and ends the lost one (rotating the old one again would leave the lost key working). Two rotations of one key at once mint one key. `keys:manage`; a key outside the caller's scope is 404 — except that a key `foldrun login` minted may rotate **itself**, whatever its role: same label, role, workspaces and 90-day lifetime from today, the old key ending 10 minutes later (`grace` is not read). A retry with the old key inside those 10 minutes — the CLI lost the answer, or could not store it — rotates that replacement instead, when nobody has used it and it is at least 30 seconds old (a younger one is a 409: another command may have just stored it). That is how the CLI renews its sign-in; any other key rotating itself still needs `keys:manage`. Audited as `apikey.rotated` (`self: true` for a self-rotation). A `foldrun login` key stays one only when it renews itself or its own person rotates it, signed in; rotated by any other caller the new key is an ordinary one |
|
|
373
372
|
| `/api/team` | GET, POST | members with their roles and workspace scope; mint an invite (a session, or the person's own `foldrun login` key, which invites no admin) — `role` (viewer \| editor \| admin, default editor), `workspaces` (names, or omit for all), `email` (only that address can accept it; sent through the account's `RESEND_API_KEY` unless `send: false`). An invite works **once**, for seven days, and a newer invite to the same address revokes the older ones still pending. Returns `id`, `path` (the invite's relative URL, shown only here), `expires`, `sent` and any `sendError` either way; the full link is in the mail. Links made before 29 Oct 2026 (`inv1`–`inv3`) are refused |
|
|
374
373
|
| `/api/team/invites?all=1` | GET | the account's invites, newest first — pending ones unless `all=1` (then accepted, revoked and expired too): `{ invites: [{ id, email, role, workspaces, invitedBy, createdAt, expiresAt, status }] }`, `email` `null` for a link anyone may use, `workspaces` `null` for all, `status` `pending` \| `accepted` \| `revoked` \| `expired`. Never the link. `team:manage` — an admin key included; a caller scoped to some workspaces sees only the invites inside its scope |
|
|
@@ -541,7 +540,7 @@ signed-in person, never by a key — mints an ordinary API key at their role.
|
|
|
541
540
|
|
|
542
541
|
## A2A — outside agents calling a published flow
|
|
543
542
|
|
|
544
|
-
Outside `/api`, and opened only by an **A2A key** (`Authorization: Bearer
|
|
543
|
+
Outside `/api`, and opened only by an **A2A key** (`Authorization: Bearer fr_a2a_…`,
|
|
545
544
|
minted with `POST /api/keys { purpose: "a2a", … }`) — never a session, never an
|
|
546
545
|
API key. They speak [A2A 1.0](a2a) over JSON-RPC 2.0, not this API: no
|
|
547
546
|
`Foldrun-Version` (the route answers `A2A-Version: 1.0` instead, and a call
|
|
@@ -560,7 +559,7 @@ published, is `404` like one that does not exist.
|
|
|
560
559
|
|
|
561
560
|
The platform as an [MCP server](mcp) for claude.ai, Claude Code, Claude
|
|
562
561
|
Desktop, Cursor, Codex and any other MCP client. An **API key**
|
|
563
|
-
(`Authorization: Bearer
|
|
562
|
+
(`Authorization: Bearer fr_api_…`) or an AI app's **OAuth access token** (below)
|
|
564
563
|
opens it — never a session cookie, never an A2A key — and every tool is a call
|
|
565
564
|
to one of the routes above, made with that credential, so it answers what the
|
|
566
565
|
route would: its role, its workspaces and every refusal hold. MCP's Streamable HTTP transport, stateless: one JSON-RPC 2.0
|
package/docs/checks.md
CHANGED
|
@@ -196,7 +196,8 @@ The OWASP ids are from the
|
|
|
196
196
|
|
|
197
197
|
*warn · ASI03.* A credential is written into a file: an Anthropic, OpenAI,
|
|
198
198
|
AWS, GitHub, GitLab, Slack, Google, Stripe, SendGrid, Twilio, Telegram, npm,
|
|
199
|
-
Hugging Face, Linear, DigitalOcean, Shopify or
|
|
199
|
+
Hugging Face, Linear, DigitalOcean, Shopify, Resend or foldrun key (`fr_api_`, `fr_gw_`,
|
|
200
|
+
`fr_a2a_`, `fr_dep_`, and the older `mda_`/`mdk_`), a JSON web token,
|
|
200
201
|
a private key, a webhook URL that carries its own secret, a password inside a
|
|
201
202
|
URL, or a field named like a credential (`api_key:`, `token:`, `password=`)
|
|
202
203
|
holding a literal value that looks random. Everything in a workspace is
|
package/docs/cli.md
CHANGED
|
@@ -132,6 +132,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
132
132
|
| `foldrun pull [workspace]` | bring the platform's account down into this folder — refuses to overwrite a locally edited file, and names every one it would have taken (`--force` takes them) |
|
|
133
133
|
| `foldrun export [workspace]` | a deployed workspace as a `.zip` — agents, flows, tools, skills, scripts, evals, knowledge; never memory, state, storage or a secret's value. `--flow <name>` exports that flow with every flow and agent it runs and the tools, skills and scripts they grant; `--agent <name>` that agent and what it grants. Written under the name the platform gives it (`<ws>.zip`, `<ws>-flow-<name>.zip`); `--file <path>` (`-` for stdout), `--force` to replace (`GET …/export`) |
|
|
134
134
|
| `foldrun import <file.zip>` | take a package in: first shows what it adds, what is identical, what it would replace and what it still needs (secrets, tools, skills, scripts, agents, flows), then asks. Never deletes; replacing a file needs `--overwrite`. `--to <workspace>` (a name that does not exist makes it, from a workspace package), `--dry-run` previews only (`--json` for the plan), `--yes` with no terminal (`POST …/import`) |
|
|
135
|
+
| `foldrun snapshot push [dir]` | send a folder for an agent on foldrun to work on (a snapshot). What goes is what git would commit — tracked files and untracked ones `.gitignore` does not exclude, as they are on disk; links and submodules are left out and named. A secret in any file stops it before anything leaves the machine (remove it, or leave the file out with `.gitignore`); the platform checks again. Answers the snapshot id, kept 7 days from the last send and while a run uses it. `--to <workspace>`, `--dry-run` packs and checks only, `--out <file.tar.gz>` keeps the archive (`--force` over a file that is there), `--json` (`POST …/snapshots`) |
|
|
135
136
|
| `foldrun status [workspace]` | per workspace: what is added, changed and only-on-the-platform, plus which files moved there since your last deploy from here. Reads only |
|
|
136
137
|
| `foldrun status --platform` | is the platform up: overall, each component (dashboard and API, run workers, scheduler, model providers, email, storage) and any incident or maintenance the operator posted, with its latest update. Reads the open `/api/status` — no key needed; the signed-in platform, `--url` / `FOLDRUN_URL`, or the default, dash.foldrun.io. `--json` prints the answer as is. Exits 1, saying *status unavailable — the platform may be down*, when it does not answer. Plain `foldrun status` opens with the same one-line verdict |
|
|
137
138
|
| `foldrun status --platform --history` | what the status page draws as bars: each component's uptime over the window and a mark per day — up, degraded or maintenance, an outage, or no samples — then the incidents and maintenance in it, from the open `GET /api/status/history?days=<n>`. `--days 1-90` (default 90), `--json` |
|
|
@@ -208,8 +209,6 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
208
209
|
| `foldrun keys ls` | the account's API keys, each with its role and scope, when it was created, when it was last used and from where (a /24 or /48), and when it expires; a key `foldrun login` minted is tagged `CLI sign-in · renews itself` (revoke it to sign that machine out) — also `create <label>` (`--expires 30d\|90d\|365d\|never`), `rotate <id>` and `revoke <id>` |
|
|
209
210
|
| `foldrun keys rotate <id>` | a new key with the old one's label, role, workspaces and deploy scope, printed once; the old key is revoked at once (asks first; `--yes` on a pipe), or keeps working for `--grace 1h` / `24h` while you swap the new one in. A key already rotated is refused (409) and the command names the key that replaced it — rotate that one, also if its secret was lost; `keys ls` shows `rotated → <id>`. The owner is emailed a week before any key expires |
|
|
210
211
|
| `foldrun keys create <label> --a2a --to <ws> --flows a,b` | a key for an outside agent ([A2A](a2a.md)): it opens `/a2a/<account>/<ws>/…` — the agent card and JSON-RPC endpoint of those flows, each published with `a2a:` (a flow not published when the key is minted is refused: publish first) — and no `/api` route. `--max-tasks <n>` caps the tasks it may have open at once (1–100, default 10); `--expires` as for any key. Printed once; `keys ls` shows it as `A2A · <ws> · <flows>`. `POST /api/keys { purpose: "a2a", workspace, flows, maxTasks }`, an admin's |
|
|
211
|
-
| `foldrun keys create <label> --gateway --cap <usd>` | a gateway key for a coding agent ([Claude Code](claude-code.md)): `ANTHROPIC_BASE_URL` + this key run Claude Code on the account's credits, through foldrun's gateway, and it opens no `/api` route. `--cap` (USD in all) and/or `--daily` (USD per UTC day) — at least one, $0.01–$100,000; `--expires` as for any key. Printed once with the two `export` lines; `keys ls` shows it as `gateway · Claude Code · $spent of $cap · $today of $daily today`. `POST /api/keys { purpose: "gateway", capUsd, dailyUsd }`, an admin of every workspace |
|
|
212
|
-
| `foldrun keys set <id> --sonnet <model>` | a gateway key's model map: which model each Claude Code tier runs on with that key (`--opus`, `--sonnet`, `--haiku`, each `provider/model` such as `openai/gpt-6`; `-` clears one, `--clear` all). The tiers named change, the rest stay. `keys ls` shows the map. `PATCH /api/keys/<id> { models }`, an admin of every workspace |
|
|
213
212
|
| `foldrun a2a ls --to <ws>` | what a workspace serves over A2A (`GET /api/workspaces/<ws>/a2a`): every flow that says `a2a:`, published or not, with its public/private card and its card and endpoint URLs; the workspace's A2A keys (an admin's view; `null` otherwise); and the newest tasks — state, flow, run, and `A2A · <key label>`; then, under **Secret and code**, every agent that holds a secret and can run code, accepted or not, with the `--accept-risk` line that accepts it. `--json` prints the answer as it came |
|
|
214
213
|
| `foldrun a2a publish <flow>` | sets `a2a: { publish: true }` in the flow, keeping the rest of its block: `--name`, `--description`, `--example "…"` (repeatable — the card's examples), `--public-card` (the card is readable without a key; calling never is) or `--private-card`. Checked with core's `a2a:` rules before anything is written; shows the diff, `--dry-run` writes nothing. Without `--to` it edits this folder (`deploy` ships it); `--to <workspace>` sends the flow page's `PATCH …/flows/<flow> { a2a, expect }` — an admin's, the platform refuses an editor — and prints the card URL. A caller also needs an A2A key that names the flow |
|
|
215
214
|
| `foldrun a2a unpublish <flow>` | `a2a: publish: false` — no outside agent may call it, whatever keys name it; the rest of `a2a:` stays for the next publish. `--to`, `--dry-run` as for `publish` |
|
|
@@ -315,7 +314,6 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
315
314
|
| `--expires <span>` | `keys create`: when it stops working — `30d`, `90d` (the default, as in the dashboard; before CLI 15.0.0 the default was never), `365d` or `never`; `--forever` is `never` |
|
|
316
315
|
| `--grace <span>` | `keys rotate`: keep the old key working for `1h` or `24h` (default `0`: revoked now) |
|
|
317
316
|
| `--a2a` | `keys create`: an A2A key for an outside agent, with `--to <workspace>`, `--flows a,b` and optionally `--max-tasks <n>` |
|
|
318
|
-
| `--gateway` | `keys create`: a gateway key for Claude Code, with `--cap <usd>` and/or `--daily <usd>` — or `--login` (the operator's Claude login, on the operator's own accounts; not metered, no limits) |
|
|
319
317
|
| `--key-env <NAME>` | `a2a call`, `a2a status`, `a2a cancel`, `a2a card`: the environment variable that holds the A2A key (default `FOLDRUN_A2A_KEY`) |
|
|
320
318
|
| `--card <url>` | `a2a status`, `a2a cancel`: the agent card of the agent that holds the task |
|
|
321
319
|
| `--force` | `deploy`: deploy while runs are in flight. `pull`, `storage get`: overwrite local files |
|
package/docs/mcp.md
CHANGED
|
@@ -71,7 +71,7 @@ Over HTTP, with a key from Settings → API keys:
|
|
|
71
71
|
|
|
72
72
|
```sh
|
|
73
73
|
claude mcp add --transport http foldrun https://<your platform>/api/mcp \
|
|
74
|
-
--header "Authorization: Bearer
|
|
74
|
+
--header "Authorization: Bearer fr_api_..."
|
|
75
75
|
```
|
|
76
76
|
|
|
77
77
|
Settings → API keys → **Connect an AI app (MCP)** shows this install's
|
|
@@ -165,7 +165,7 @@ that act are not offered, and a call to one is refused:
|
|
|
165
165
|
|
|
166
166
|
```sh
|
|
167
167
|
claude mcp add foldrun -- foldrun mcp --read-only
|
|
168
|
-
claude mcp add --transport http foldrun "https://<your platform>/api/mcp?readonly=1" --header "Authorization: Bearer
|
|
168
|
+
claude mcp add --transport http foldrun "https://<your platform>/api/mcp?readonly=1" --header "Authorization: Bearer fr_api_..."
|
|
169
169
|
```
|
|
170
170
|
|
|
171
171
|
A viewer's key is the stronger version of the same: read-only by role,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "20.
|
|
3
|
+
"version": "20.7.0",
|
|
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",
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
],
|
|
23
23
|
"scripts": {
|
|
24
24
|
"e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
|
|
25
|
-
"test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-team-me.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts tests/cli-gateway.test.ts tests/cli-switches.test.ts tests/cli-parity-runs.test.ts tests/cli-parity-b.test.ts tests/cli-parity-clears.test.ts tests/cli-parity-c.test.ts tests/cli-runs-paging.test.ts tests/cli-budget-invoices.test.ts tests/cli-observe-analysis.test.ts tests/cli-failure-retention.test.ts",
|
|
25
|
+
"test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-team-me.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts tests/cli-gateway.test.ts tests/cli-switches.test.ts tests/cli-parity-runs.test.ts tests/cli-parity-b.test.ts tests/cli-parity-clears.test.ts tests/cli-parity-c.test.ts tests/cli-runs-paging.test.ts tests/cli-budget-invoices.test.ts tests/cli-observe-analysis.test.ts tests/cli-failure-retention.test.ts tests/cli-snapshot.test.ts",
|
|
26
26
|
"release": "node scripts/release.mjs",
|
|
27
27
|
"typecheck": "tsc -p tsconfig.json",
|
|
28
28
|
"docs:sync": "node scripts/sync-docs.mjs",
|
package/src/commands.mjs
CHANGED
|
@@ -11,7 +11,7 @@ import path from "node:path";
|
|
|
11
11
|
import { fileURLToPath } from "node:url";
|
|
12
12
|
import { writeAgentFiles, hasCurrentAgentRules, agentRulesBlock, codingAgent, docsDir, docPages, docPage } from "./guide.mjs";
|
|
13
13
|
import { createRequire } from "node:module";
|
|
14
|
-
import { execFileSync } from "node:child_process";
|
|
14
|
+
import { execFileSync, spawnSync } from "node:child_process";
|
|
15
15
|
import { defaultPlatform, saveCredential, removeCredential, normaliseUrl, profileByName, currentProfile, useProfile, listProfiles, credentialsDir } from "./credentials.mjs";
|
|
16
16
|
|
|
17
17
|
// NO_COLOR (no-color.org) turns the escapes off — for a log file, a CI
|
|
@@ -4697,6 +4697,7 @@ async function doctor(flags) {
|
|
|
4697
4697
|
* keys create <label> --a2a --to <ws> --flows a,b [--max-tasks N] a key for an outside agent: /a2a only
|
|
4698
4698
|
* keys create <label> --gateway --cap <usd> [--daily <usd>] a coding agent's key (Claude Code): the gateway only
|
|
4699
4699
|
* keys create <label> --gateway --login on the operator's Claude login (its own accounts): not metered
|
|
4700
|
+
* keys create <label> --gateway --cap <usd> --claude-code …and write it into Claude Code's settings
|
|
4700
4701
|
* keys set <id> --opus|--sonnet|--haiku <provider/model> which model each Claude Code tier runs on (a gateway key; `-` clears one, --clear all)
|
|
4701
4702
|
* keys rotate <id> [--grace 1h] a new key, same label/role/scope; the old
|
|
4702
4703
|
* one ends now, or when the grace runs out.
|
|
@@ -4744,6 +4745,7 @@ async function keysCmd(positional, flags) {
|
|
|
4744
4745
|
if (verb === "create" || verb === "new") {
|
|
4745
4746
|
if (!arg) throw new Error("what is the key for? foldrun keys create <label>");
|
|
4746
4747
|
if (flags.a2a === true && flags.gateway === true) throw new Error("--a2a or --gateway, not both");
|
|
4748
|
+
if (flags["claude-code"] === true && flags.gateway !== true) throw new Error("--claude-code goes with --gateway: only a gateway key runs Claude Code");
|
|
4747
4749
|
if (flags.a2a === true) return keysCreateA2a(url, arg, flags);
|
|
4748
4750
|
if (flags.gateway === true) return keysCreateGateway(url, arg, flags);
|
|
4749
4751
|
const body = { label: arg };
|
|
@@ -4905,6 +4907,9 @@ async function keysCreateGateway(url, label, flags) {
|
|
|
4905
4907
|
const capUsd = flags.login === true ? undefined : usdFlag(flags.cap, "--cap");
|
|
4906
4908
|
const dailyUsd = flags.login === true ? undefined : usdFlag(flags.daily, "--daily");
|
|
4907
4909
|
if (flags.login !== true && capUsd === undefined && dailyUsd === undefined) throw new Error("a gateway key needs a limit of its own: --cap <usd> in all, or --daily <usd> per UTC day (or both) — or --login, on an account the operator's Claude login is for");
|
|
4910
|
+
// --claude-code: read Claude Code's settings BEFORE minting, so a file we
|
|
4911
|
+
// could not safely rewrite stops here with nothing made.
|
|
4912
|
+
const claude = flags["claude-code"] === true ? preflightClaudeSettings() : null;
|
|
4908
4913
|
const body = { label, purpose: "gateway" };
|
|
4909
4914
|
if (flags.login === true) body.credential = "login";
|
|
4910
4915
|
if (capUsd !== undefined) body.capUsd = capUsd;
|
|
@@ -4918,9 +4923,27 @@ async function keysCreateGateway(url, label, flags) {
|
|
|
4918
4923
|
if (made.key == null) return lostSecret(made.id);
|
|
4919
4924
|
console.log(` ${made.key}\n`);
|
|
4920
4925
|
const base = made.gatewayUrl ?? "<the gateway URL — not set on this platform yet>";
|
|
4921
|
-
|
|
4922
|
-
|
|
4923
|
-
|
|
4926
|
+
// Written from the file as it is NOW, not as it was before the request,
|
|
4927
|
+
// so a change made meanwhile is kept. A write that fails after the key
|
|
4928
|
+
// exists says so and falls back to the lines to copy.
|
|
4929
|
+
/** @type {{ file: string, dropped: string[], backup: string | null } | null} */
|
|
4930
|
+
let done = null;
|
|
4931
|
+
if (claude && made.gatewayUrl) {
|
|
4932
|
+
try { done = writeClaudeSettings(readClaudeSettings(), made.gatewayUrl, made.key); }
|
|
4933
|
+
catch (e) { console.log(` ${c.yellow(`The key was made, but Claude Code's settings were not written: ${e.message}`)}\n`); }
|
|
4934
|
+
}
|
|
4935
|
+
if (done) {
|
|
4936
|
+
console.log(` ${c.green("✓")} ${c.dim("Claude Code now runs on it — written to")} ${done.file}`);
|
|
4937
|
+
console.log(` ${c.dim(`env: ANTHROPIC_BASE_URL=${made.gatewayUrl}, ANTHROPIC_AUTH_TOKEN=<this key>`)}`);
|
|
4938
|
+
if (done.dropped.length) console.log(` ${c.dim(`removed from that env block: ${done.dropped.join(", ")} (it would have competed with the key)`)}`);
|
|
4939
|
+
if (done.backup) console.log(` ${c.dim(`the file as it was: ${done.backup}`)}`);
|
|
4940
|
+
console.log(` ${c.dim("Start a new claude session; /status shows the gateway. Claude Desktop is set in its own Developer → Configure Third-Party Inference.")}\n`);
|
|
4941
|
+
} else {
|
|
4942
|
+
if (claude && !made.gatewayUrl) console.log(` ${c.yellow("This platform has no gateway URL yet, so Claude Code's settings were not written.")}\n`);
|
|
4943
|
+
console.log(` ${c.dim("Shown once. Point Claude Code at it:")}\n`);
|
|
4944
|
+
console.log(` export ANTHROPIC_BASE_URL=${base}`);
|
|
4945
|
+
console.log(` export ANTHROPIC_API_KEY=<key>\n`);
|
|
4946
|
+
}
|
|
4924
4947
|
// A login key is not metered: there is no spend for `keys ls` to show.
|
|
4925
4948
|
const after = made.credential === "login"
|
|
4926
4949
|
? `It opens the gateway only and runs on the operator's Claude login, not metered — it shares that subscription's weekly cap with the desks. \`foldrun keys revoke ${made.id}\` ends it.`
|
|
@@ -4929,6 +4952,76 @@ async function keysCreateGateway(url, label, flags) {
|
|
|
4929
4952
|
return 0;
|
|
4930
4953
|
}
|
|
4931
4954
|
|
|
4955
|
+
/** Claude Code's user settings: $CLAUDE_CONFIG_DIR/settings.json, else
|
|
4956
|
+
* ~/.claude/settings.json (%USERPROFILE%\.claude on Windows). Its env block
|
|
4957
|
+
* reaches the CLI, the IDE extensions' sessions and background agents. */
|
|
4958
|
+
function claudeSettingsFile() {
|
|
4959
|
+
const dir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
|
|
4960
|
+
return path.join(dir, "settings.json");
|
|
4961
|
+
}
|
|
4962
|
+
|
|
4963
|
+
/** Read Claude Code's settings for `keys create --gateway --claude-code`,
|
|
4964
|
+
* refusing anything we could not rewrite without losing what is there: a
|
|
4965
|
+
* file that is not a JSON object, or an env that is not one. */
|
|
4966
|
+
function readClaudeSettings() {
|
|
4967
|
+
const file = claudeSettingsFile();
|
|
4968
|
+
/** @type {string | null} */
|
|
4969
|
+
let text = null;
|
|
4970
|
+
try { text = fs.readFileSync(file, "utf8"); } catch (e) { if (e.code !== "ENOENT") throw new Error(`cannot read ${file}: ${e.message}`); }
|
|
4971
|
+
/** @type {any} */
|
|
4972
|
+
let settings = {};
|
|
4973
|
+
if (text !== null && text.trim()) {
|
|
4974
|
+
try { settings = JSON.parse(text); } catch { throw new Error(`${file} is not valid JSON, so it was left alone — fix the file, or leave out --claude-code and set the two lines by hand`); }
|
|
4975
|
+
}
|
|
4976
|
+
if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error(`${file} is not a JSON object, so it was left alone`);
|
|
4977
|
+
if (settings.env !== undefined && (!settings.env || typeof settings.env !== "object" || Array.isArray(settings.env))) throw new Error(`${file} has an "env" that is not an object, so it was left alone`);
|
|
4978
|
+
return { file, text, settings };
|
|
4979
|
+
}
|
|
4980
|
+
|
|
4981
|
+
/** Before a key is made: the settings can be read and rewritten — the
|
|
4982
|
+
* folder exists or can be made, and a file can be written in it. Anything
|
|
4983
|
+
* else stops here, with no key made. */
|
|
4984
|
+
function preflightClaudeSettings() {
|
|
4985
|
+
try {
|
|
4986
|
+
const found = readClaudeSettings();
|
|
4987
|
+
fs.mkdirSync(path.dirname(found.file), { recursive: true, mode: 0o700 });
|
|
4988
|
+
const probe = `${found.file}.${process.pid}.probe`;
|
|
4989
|
+
fs.writeFileSync(probe, "", { mode: 0o600 });
|
|
4990
|
+
fs.rmSync(probe, { force: true });
|
|
4991
|
+
if (found.text !== null) fs.accessSync(found.file, fs.constants.W_OK);
|
|
4992
|
+
return found;
|
|
4993
|
+
} catch (e) {
|
|
4994
|
+
throw new Error(`${e.message} — no key was made`);
|
|
4995
|
+
}
|
|
4996
|
+
}
|
|
4997
|
+
|
|
4998
|
+
/** Put the gateway URL and key into Claude Code's env block, keeping every
|
|
4999
|
+
* other setting. ANTHROPIC_AUTH_TOKEN (a Bearer) wins over a saved Claude
|
|
5000
|
+
* login with no prompt; an ANTHROPIC_API_KEY in the same block would compete
|
|
5001
|
+
* with it, so it goes. The old file is kept beside it, the new one is
|
|
5002
|
+
* written whole (a temp file, then a rename) and readable only by you. */
|
|
5003
|
+
function writeClaudeSettings({ file, text, settings }, baseUrl, key) {
|
|
5004
|
+
const env = { ...(settings.env ?? {}) };
|
|
5005
|
+
const dropped = ["ANTHROPIC_API_KEY"].filter((k) => k in env);
|
|
5006
|
+
for (const k of dropped) delete env[k];
|
|
5007
|
+
env.ANTHROPIC_BASE_URL = baseUrl;
|
|
5008
|
+
env.ANTHROPIC_AUTH_TOKEN = key;
|
|
5009
|
+
const next = { ...settings, env };
|
|
5010
|
+
fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
|
|
5011
|
+
/** @type {string | null} */
|
|
5012
|
+
let backup = null;
|
|
5013
|
+
if (text !== null) {
|
|
5014
|
+
backup = `${file}.before-foldrun`;
|
|
5015
|
+
fs.writeFileSync(backup, text, { mode: 0o600 });
|
|
5016
|
+
try { fs.chmodSync(backup, 0o600); } catch { /* Windows: no modes */ }
|
|
5017
|
+
}
|
|
5018
|
+
const tmp = `${file}.${process.pid}.tmp`;
|
|
5019
|
+
fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
|
|
5020
|
+
fs.renameSync(tmp, file);
|
|
5021
|
+
try { fs.chmodSync(file, 0o600); } catch { /* Windows: no modes */ }
|
|
5022
|
+
return { file, dropped, backup };
|
|
5023
|
+
}
|
|
5024
|
+
|
|
4932
5025
|
/** A retried mint or rotate is answered from the first call, and the server
|
|
4933
5026
|
* never stores a key's secret — so a retry after a lost answer has none. */
|
|
4934
5027
|
function lostSecret(id) {
|
|
@@ -11365,6 +11458,130 @@ async function importCmd(positional, flags, layout) {
|
|
|
11365
11458
|
return 0;
|
|
11366
11459
|
}
|
|
11367
11460
|
|
|
11461
|
+
/**
|
|
11462
|
+
* `foldrun snapshot push [dir] --to <workspace>` — send a folder for an agent
|
|
11463
|
+
* on foldrun to work on (Part B3). What goes is what git would commit: the
|
|
11464
|
+
* tracked files and the untracked ones .gitignore does not exclude
|
|
11465
|
+
* (`git ls-files --cached --others --exclude-standard`), as they are on disk
|
|
11466
|
+
* now. Links and anything that is not a plain file are left out and named.
|
|
11467
|
+
* Checked HERE before anything leaves the machine — a secret in any file
|
|
11468
|
+
* stops it, with no way to silence it but removing the secret or the file —
|
|
11469
|
+
* and checked again by the platform. Answers the snapshot id a run takes.
|
|
11470
|
+
*/
|
|
11471
|
+
async function snapshotCmd(positional, flags, layout) {
|
|
11472
|
+
const verb = positional[0];
|
|
11473
|
+
if (verb !== "push") throw new Error("`foldrun snapshot push [dir] --to <workspace>` — send a git folder for an agent on foldrun to work on (--dry-run, --out <file.tar.gz> [--force], --json)");
|
|
11474
|
+
const dir = path.resolve(positional[1] ?? ".");
|
|
11475
|
+
if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) throw new Error(`${dir} is not a folder`);
|
|
11476
|
+
const git = spawnSync("git", ["-C", dir, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { encoding: "buffer", maxBuffer: 256 * 1024 * 1024 });
|
|
11477
|
+
if (git.error || git.status !== 0) {
|
|
11478
|
+
throw new Error(`${dir} is not in a git repository — a snapshot sends what git would commit, so \`git init\` it first (${String(git.stderr ?? git.error?.message ?? "").trim().split("\n")[0]})`);
|
|
11479
|
+
}
|
|
11480
|
+
const { packSnapshot, SnapshotRefused, SNAPSHOT_LIMITS } = await import("@foldrun/core/snapshot-archive");
|
|
11481
|
+
const { uploadSecretFindings } = await import("@foldrun/core/scan");
|
|
11482
|
+
const names = [...new Set(git.stdout.toString("utf8").split("\0").filter(Boolean))].sort();
|
|
11483
|
+
const entries = [];
|
|
11484
|
+
const left = [];
|
|
11485
|
+
let total = 0;
|
|
11486
|
+
const realDir = fs.realpathSync(dir);
|
|
11487
|
+
for (const rel of names) {
|
|
11488
|
+
const abs = path.join(dir, rel);
|
|
11489
|
+
let st;
|
|
11490
|
+
try {
|
|
11491
|
+
st = fs.lstatSync(abs);
|
|
11492
|
+
} catch {
|
|
11493
|
+
continue; // tracked, but deleted on disk: it is not in the folder now
|
|
11494
|
+
}
|
|
11495
|
+
// lstat looks through a link in a PARENT: a tracked folder replaced by a
|
|
11496
|
+
// link to elsewhere still lists its old children (Codex). A file goes only
|
|
11497
|
+
// when its real path is exactly <folder>/<path> — no link on the way.
|
|
11498
|
+
if (st.isFile()) {
|
|
11499
|
+
let real = "";
|
|
11500
|
+
try {
|
|
11501
|
+
real = fs.realpathSync(abs);
|
|
11502
|
+
} catch {
|
|
11503
|
+
/* gone meanwhile */
|
|
11504
|
+
}
|
|
11505
|
+
if (real !== path.join(realDir, rel)) {
|
|
11506
|
+
left.push(`${rel} (under a link)`);
|
|
11507
|
+
continue;
|
|
11508
|
+
}
|
|
11509
|
+
}
|
|
11510
|
+
if (!st.isFile()) {
|
|
11511
|
+
left.push(`${rel} (${st.isSymbolicLink() ? "a link" : st.isDirectory() ? "a submodule" : "not a plain file"})`);
|
|
11512
|
+
continue;
|
|
11513
|
+
}
|
|
11514
|
+
if (st.size > SNAPSHOT_LIMITS.maxFileBytes) throw new Error(`${rel} is ${st.size} bytes — the most for one file is ${SNAPSHOT_LIMITS.maxFileBytes}; add it to .gitignore or remove it`);
|
|
11515
|
+
total += st.size;
|
|
11516
|
+
if (total > SNAPSHOT_LIMITS.maxTotalBytes) throw new Error(`the folder is past ${SNAPSHOT_LIMITS.maxTotalBytes} bytes — leave out build output and dependencies (.gitignore)`);
|
|
11517
|
+
entries.push({ path: rel, mode: st.mode & 0o111 ? 0o755 : 0o644, content: fs.readFileSync(abs) });
|
|
11518
|
+
}
|
|
11519
|
+
if (!entries.length) throw new Error(`nothing to send — git sees no files in ${dir}`);
|
|
11520
|
+
|
|
11521
|
+
const scan = uploadSecretFindings(entries.map((e) => ({ path: e.path, content: e.content.toString("utf8") })));
|
|
11522
|
+
if (scan.findings.length) {
|
|
11523
|
+
for (const f of scan.findings.slice(0, 20)) console.error(` ${c.red("✗")} ${f.file}${f.line ? `:${f.line}` : ""} ${c.dim(f.rule)}`);
|
|
11524
|
+
throw new Error(`not sent: ${scan.findings.length} place${scan.findings.length === 1 ? "" : "s"} look${scan.findings.length === 1 ? "s" : ""} like a secret — remove ${scan.findings.length === 1 ? "it" : "them"} (or leave the file out with .gitignore) and push again; a snapshot cannot carry one`);
|
|
11525
|
+
}
|
|
11526
|
+
|
|
11527
|
+
// Files the scanner cannot read as text (a NUL early on): sent, but named,
|
|
11528
|
+
// so nobody takes "checked for secrets" to cover them.
|
|
11529
|
+
const unscanned = scan.unscanned;
|
|
11530
|
+
let packed;
|
|
11531
|
+
try {
|
|
11532
|
+
packed = packSnapshot(entries);
|
|
11533
|
+
} catch (err) {
|
|
11534
|
+
if (err instanceof SnapshotRefused) throw new Error(`not sent: ${err.message}`);
|
|
11535
|
+
throw err;
|
|
11536
|
+
}
|
|
11537
|
+
if (typeof flags.out === "string") {
|
|
11538
|
+
// Never over a file that is there unless asked (--force), as export does:
|
|
11539
|
+
// a preview must not be able to destroy a file named by mistake (Codex).
|
|
11540
|
+
if (fs.existsSync(flags.out) && flags.force !== true) throw new Error(`${flags.out} already exists — --force replaces it`);
|
|
11541
|
+
fs.writeFileSync(flags.out, packed.archive);
|
|
11542
|
+
}
|
|
11543
|
+
const summary = `${packed.files} file${packed.files === 1 ? "" : "s"}, ${packed.bytes} bytes (${packed.archive.length} compressed)`;
|
|
11544
|
+
if (flags["dry-run"] === true) {
|
|
11545
|
+
if (flags.json === true) console.log(JSON.stringify({ dryRun: true, snapshotId: packed.sha256, files: packed.files, bytes: packed.bytes, compressedBytes: packed.archive.length, leftOut: left, unscanned }, null, 2));
|
|
11546
|
+
else {
|
|
11547
|
+
console.log(`\n ${c.bold(summary)} ${c.dim(`· ${packed.sha256.slice(0, 12)}`)}`);
|
|
11548
|
+
for (const l of left.slice(0, 20)) console.log(` ${c.dim(`left out: ${l}`)}`);
|
|
11549
|
+
if (unscanned.length) console.log(` ${c.amber("!")} not checked for secrets (binary): ${unscanned.slice(0, 10).join(", ")}${unscanned.length > 10 ? " …" : ""}`);
|
|
11550
|
+
console.log(`\n ${c.dim("(--dry-run: nothing sent)")}\n`);
|
|
11551
|
+
}
|
|
11552
|
+
return 0;
|
|
11553
|
+
}
|
|
11554
|
+
|
|
11555
|
+
const url = platformFor(flags, "snapshot push");
|
|
11556
|
+
const ws = platformWorkspace(flags, layout, "snapshot push");
|
|
11557
|
+
const token = await renewedToken(url, flags);
|
|
11558
|
+
const res = await remoteFetch(
|
|
11559
|
+
url,
|
|
11560
|
+
`/api/workspaces/${enc(ws)}/snapshots`,
|
|
11561
|
+
{ method: "POST", body: packed.archive, headers: { "content-type": "application/gzip" } },
|
|
11562
|
+
{ token, seconds: timeoutSeconds(flags) },
|
|
11563
|
+
);
|
|
11564
|
+
const text = await res.text();
|
|
11565
|
+
let body = {};
|
|
11566
|
+
try {
|
|
11567
|
+
body = text.trim() ? JSON.parse(text) : {};
|
|
11568
|
+
} catch {
|
|
11569
|
+
/* not JSON — the status says enough */
|
|
11570
|
+
}
|
|
11571
|
+
if (!res.ok) throw new HttpError(`${body.error ?? `snapshot push → HTTP ${res.status}`}${res.status === 401 || res.status === 403 ? refusedHint(url, flags) : ""}`, res.status, body);
|
|
11572
|
+
if (flags.json === true) {
|
|
11573
|
+
console.log(JSON.stringify({ ...body, leftOut: left, unscanned }, null, 2));
|
|
11574
|
+
return 0;
|
|
11575
|
+
}
|
|
11576
|
+
console.log(`\n ${c.green("✓")} ${summary} → ${c.bold(ws)}${body.reused ? c.dim(" (already there)") : ""}`);
|
|
11577
|
+
console.log(` snapshot ${c.bold(String(body.snapshotId))}`);
|
|
11578
|
+
console.log(` ${c.dim(`kept until ${body.expiresAt}, and while a run uses it`)}`);
|
|
11579
|
+
for (const l of left.slice(0, 20)) console.log(` ${c.dim(`left out: ${l}`)}`);
|
|
11580
|
+
if (unscanned.length) console.log(` ${c.amber("!")} not checked for secrets (binary): ${unscanned.slice(0, 10).join(", ")}${unscanned.length > 10 ? " …" : ""}`);
|
|
11581
|
+
console.log();
|
|
11582
|
+
return 0;
|
|
11583
|
+
}
|
|
11584
|
+
|
|
11368
11585
|
/**
|
|
11369
11586
|
* `foldrun report <run-id> get <agent>/<path>` — one file a run archived:
|
|
11370
11587
|
* whatever an agent left in outputs/, copied under the run when it ended.
|
|
@@ -14870,6 +15087,8 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
14870
15087
|
return exportCmd(positional, flags, layout);
|
|
14871
15088
|
case "import":
|
|
14872
15089
|
return importCmd(positional, flags, layout);
|
|
15090
|
+
case "snapshot":
|
|
15091
|
+
return snapshotCmd(positional, flags, layout);
|
|
14873
15092
|
case "status":
|
|
14874
15093
|
return statusCmd(layout, flags, positional[0]);
|
|
14875
15094
|
case "workspaces":
|
package/docs/claude-code.md
DELETED
|
@@ -1,180 +0,0 @@
|
|
|
1
|
-
# Claude Code on foldrun's models
|
|
2
|
-
|
|
3
|
-
Claude Code — and any tool that takes an Anthropic base URL and key — can run
|
|
4
|
-
on your foldrun account's credits instead of an Anthropic account of your
|
|
5
|
-
own. You mint a **gateway key**, point the tool at foldrun's gateway, and
|
|
6
|
-
every call is billed to the account at foldrun's price list, up to the key's
|
|
7
|
-
own limits.
|
|
8
|
-
|
|
9
|
-
```sh
|
|
10
|
-
export ANTHROPIC_BASE_URL=https://<the gateway URL> # Settings → API keys shows it
|
|
11
|
-
export ANTHROPIC_API_KEY=mda_… # the gateway key
|
|
12
|
-
claude
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
`ANTHROPIC_AUTH_TOKEN` works in place of `ANTHROPIC_API_KEY` (it is sent as
|
|
16
|
-
`Authorization: Bearer`). This is on the hosted platform only; a self-hosted
|
|
17
|
-
install has no gateway.
|
|
18
|
-
|
|
19
|
-
## Minting a gateway key
|
|
20
|
-
|
|
21
|
-
On **Settings → API keys**, pick **Gateway key — Claude Code** as the kind,
|
|
22
|
-
or from a terminal:
|
|
23
|
-
|
|
24
|
-
```sh
|
|
25
|
-
foldrun keys create laptop --gateway --cap 20 --daily 5
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
- **A limit of its own is required:** `--cap` (USD, in all) or `--daily`
|
|
29
|
-
(USD, per UTC day), or both — from $0.01 to $100,000.
|
|
30
|
-
Limits are in dollars charged — what the account pays at foldrun's price
|
|
31
|
-
list — and so is the spend `keys ls` shows. Each call is kept at the
|
|
32
|
-
margin it was charged at, so a margin changed later re-prices nothing.
|
|
33
|
-
- **Who may mint one:** an admin of every workspace. The key spends the
|
|
34
|
-
whole account's balance, so a workspace-scoped admin cannot.
|
|
35
|
-
- **What it opens:** the gateway only. Every `/api` route refuses it (403),
|
|
36
|
-
so it cannot read a workspace, start a run or mint a key. An account API
|
|
37
|
-
key is refused by the gateway the same way.
|
|
38
|
-
- **Shown once**, like every key. `foldrun keys ls` (and the Settings list)
|
|
39
|
-
shows what it has spent against each limit; `rotate` keeps its limits, and
|
|
40
|
-
the new key's spend starts afresh; `revoke` ends it at once.
|
|
41
|
-
|
|
42
|
-
The API is `POST /api/keys { purpose: "gateway", capUsd?, dailyUsd?, label?, expires? }`
|
|
43
|
-
([API](api.md)).
|
|
44
|
-
|
|
45
|
-
## On the operator's Claude login
|
|
46
|
-
|
|
47
|
-
An account the operator allows its own model credential — the one its desks
|
|
48
|
-
run on — may mint a gateway key on the operator's Claude login instead:
|
|
49
|
-
|
|
50
|
-
```sh
|
|
51
|
-
foldrun keys create mine --gateway --login
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
or **Runs on → The operator's Claude login** on Settings → API keys (shown
|
|
55
|
-
only on such an account). Such a key:
|
|
56
|
-
|
|
57
|
-
- sends the operator's Claude login to Anthropic, read fresh on every call,
|
|
58
|
-
so the platform's token refresh reaches it with no restart;
|
|
59
|
-
- is **not metered or billed** and takes no `--cap` or `--daily` — the
|
|
60
|
-
login is a flat-rate subscription, so there is no dollar figure to hold;
|
|
61
|
-
- shares that subscription's weekly cap with the account's desks: a long
|
|
62
|
-
coding session can leave the desks out of their window until it resets;
|
|
63
|
-
- opens nothing once the account is no longer allowed the credential: the
|
|
64
|
-
gateway asks on every call.
|
|
65
|
-
|
|
66
|
-
It is for the operator's own use. A subscription's terms are its owner's to
|
|
67
|
-
keep; foldrun's models (the rest of this page) are what to give anyone else.
|
|
68
|
-
|
|
69
|
-
## Other providers' models
|
|
70
|
-
|
|
71
|
-
The same key reaches OpenAI's, Gemini's, DeepSeek's, Kimi's, Z.ai's (GLM),
|
|
72
|
-
Alibaba's (Qwen), MiniMax's and Xiaomi's (MiMo) models: name one, and the
|
|
73
|
-
gateway sends it to that provider on foldrun's models (billed at its price,
|
|
74
|
-
under the same limits).
|
|
75
|
-
|
|
76
|
-
```sh
|
|
77
|
-
claude --model deepseek/deepseek-v4 # or /model deepseek/deepseek-v4 in a session
|
|
78
|
-
claude --model kimi/kimi-k3
|
|
79
|
-
claude --model openai/gpt-6 # or gpt-6
|
|
80
|
-
claude --model gemini/gemini-3-pro # or gemini-3-pro
|
|
81
|
-
claude --model glm-5.3 # Z.ai
|
|
82
|
-
claude --model qwen3.8-max # Alibaba
|
|
83
|
-
claude --model MiniMax-M3 # MiniMax
|
|
84
|
-
claude --model mimo-v2.6-pro # Xiaomi
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
- **Choosing a provider.** `provider/model` always works (`anthropic/`,
|
|
88
|
-
`openai/`, `gemini/`, `deepseek/`, `kimi/`, `zai/`, `qwen/`, `minimax/`,
|
|
89
|
-
`mimo/`). A bare name with a known prefix works too: `gpt-…`, `gemini-…`,
|
|
90
|
-
`deepseek-…`, `kimi-…`, `glm-…`, `qwen…`, `minimax-…`, `mimo-…`, or
|
|
91
|
-
`claude-…` for Anthropic. Anything else goes to Anthropic.
|
|
92
|
-
- **How each is reached.** DeepSeek, Kimi, Z.ai, Qwen, MiniMax and MiMo speak
|
|
93
|
-
Anthropic's format and are sent as they are, less what each one's API does
|
|
94
|
-
not document (context editing, Claude's tool search, `service_tier`;
|
|
95
|
-
`thinking` in the words each one takes). OpenAI (Responses API) and Gemini (Chat Completions) are
|
|
96
|
-
translated both ways, by the same translator runs use.
|
|
97
|
-
- Tools work on all of them.
|
|
98
|
-
- Gemini's thought signatures are kept between your calls (in the
|
|
99
|
-
platform's cache, per account, for two hours), so a multi-turn tool loop
|
|
100
|
-
works on Gemini too.
|
|
101
|
-
- Translation drops prompt caching, thinking where the provider has none,
|
|
102
|
-
and Anthropic's server tools (web search, web fetch).
|
|
103
|
-
- **What Claude Code sends.** It sends the name you give it unchanged.
|
|
104
|
-
Claude Code's own `/model` list shows Claude models only, so type the name.
|
|
105
|
-
Each provider gets only the request fields its API takes; the rest are
|
|
106
|
-
dropped.
|
|
107
|
-
- **Token counts.** A provider with no token-count route gets an estimate
|
|
108
|
-
(marked `x-foldrun-estimate: 1`).
|
|
109
|
-
- **What Claude Code can't know.** For non-Claude models it shows the wrong
|
|
110
|
-
cost and context size. The charge is foldrun's.
|
|
111
|
-
- **What isn't offered.** A login gateway key stays Claude-only.
|
|
112
|
-
|
|
113
|
-
## Run Claude Code's own tiers on other models
|
|
114
|
-
|
|
115
|
-
Claude Code's `/model` list shows Claude's tiers alone. A gateway key can map
|
|
116
|
-
each tier to any model foldrun offers, so picking Sonnet in `/model` (or
|
|
117
|
-
`--model sonnet`) runs, say, GPT — with no setting in Claude Code at all:
|
|
118
|
-
|
|
119
|
-
```sh
|
|
120
|
-
foldrun keys set <id> --sonnet openai/gpt-6 --haiku deepseek/deepseek-v4
|
|
121
|
-
foldrun keys set <id> --haiku - # Haiku back to Claude
|
|
122
|
-
foldrun keys set <id> --clear # every tier as Claude Code names it
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
On Settings → API keys, a gateway key's **Models** button does the same, and
|
|
126
|
-
the row shows what each tier runs on. A mapped model must be on foldrun's
|
|
127
|
-
price list; a login gateway key maps to Claude models only. The gateway reads a
|
|
128
|
-
change within 10 seconds. API: `PATCH /api/keys/<id> { models }`, or `models`
|
|
129
|
-
when minting.
|
|
130
|
-
|
|
131
|
-
## What the gateway serves
|
|
132
|
-
|
|
133
|
-
| Route | |
|
|
134
|
-
|---|---|
|
|
135
|
-
| `POST /v1/messages` | metered, streamed or not |
|
|
136
|
-
| `POST /v1/messages/count_tokens` | free |
|
|
137
|
-
| `GET /v1/models` | free |
|
|
138
|
-
|
|
139
|
-
Anything else is a 404; a query string (`/v1/models?after_id=…`) goes on as
|
|
140
|
-
it came. Anthropic's models only. Your key never reaches
|
|
141
|
-
Anthropic: the gateway sends the call with the platform's own key, and only
|
|
142
|
-
the headers Anthropic's API reads (`anthropic-version`, `anthropic-beta`,
|
|
143
|
-
`content-type`, `accept`).
|
|
144
|
-
|
|
145
|
-
## Limits and refusals
|
|
146
|
-
|
|
147
|
-
Each call is checked the way a run's call on foldrun's models is
|
|
148
|
-
([budgets and billing](budgets-and-billing.md)):
|
|
149
|
-
|
|
150
|
-
- the account must have credit, and foldrun's models must be on for it;
|
|
151
|
-
- the model must be on the price list;
|
|
152
|
-
- the call is held at the most it could cost (its input, and every output
|
|
153
|
-
token it may ask for) against the account's daily limit **and** the key's
|
|
154
|
-
own limits, before it is sent — so calls at once cannot pass a limit
|
|
155
|
-
together, and a call that would pass one is refused, not cut off midway;
|
|
156
|
-
- it is charged what Anthropic reports it used, or its hold if no usage
|
|
157
|
-
came back (a reply cut short).
|
|
158
|
-
|
|
159
|
-
Because a call is held at its most, a key's limit needs room for the
|
|
160
|
-
calls Claude Code makes at once — a few dollars, not cents.
|
|
161
|
-
|
|
162
|
-
Request fields billed outside tokens are refused until they have a price:
|
|
163
|
-
server tools (web search, code execution), a one-hour prompt cache, a
|
|
164
|
-
priority tier.
|
|
165
|
-
|
|
166
|
-
A refusal comes back in Anthropic's own error shape, so Claude Code prints
|
|
167
|
-
the reason:
|
|
168
|
-
|
|
169
|
-
| Status | Why |
|
|
170
|
-
|---|---|
|
|
171
|
-
| `401` | no key, an unknown, revoked or expired key |
|
|
172
|
-
| `403` | not a gateway key; foldrun's models off for the account |
|
|
173
|
-
| `402` | out of credits; the key's limit or the account's daily limit has no room; a model with no price |
|
|
174
|
-
| `429` | the key's request rate (300 a minute) or its open calls (32 at once) — with `Retry-After`; waiting helps. Every route and every kind of key counts |
|
|
175
|
-
| `400` | a request field that is not offered (named in the message) |
|
|
176
|
-
|
|
177
|
-
A key that is revoked can still answer for up to 10 seconds: each gateway pod
|
|
178
|
-
caches a key for that long. A spent limit is a `402`, not a `429`: Claude Code retries a `429` for minutes,
|
|
179
|
-
and no retry makes room under a limit. A `429` from Anthropic itself comes
|
|
180
|
-
back as it was.
|