foldrun 19.1.0 → 19.2.1
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/README.md +2 -1
- package/bin/foldrun.mjs +1 -0
- package/docs/api.md +2 -2
- package/docs/cli.md +6 -5
- package/docs/self-hosting.md +5 -1
- package/package.json +2 -2
- package/src/commands.mjs +58 -1
package/README.md
CHANGED
|
@@ -227,7 +227,8 @@ foldrun deploy
|
|
|
227
227
|
foldrun invoke publish --wait
|
|
228
228
|
```
|
|
229
229
|
|
|
230
|
-
`foldrun login
|
|
230
|
+
`foldrun login` signs in to the hosted platform, https://dash.foldrun.io;
|
|
231
|
+
`foldrun login --url https://your-platform` (or `FOLDRUN_URL`) to your own installation.
|
|
231
232
|
In CI, set `FOLDRUN_URL` and `FOLDRUN_TOKEN` instead — the environment always
|
|
232
233
|
wins over the credentials file, so a job never reads one from disk.
|
|
233
234
|
|
package/bin/foldrun.mjs
CHANGED
|
@@ -286,6 +286,7 @@ Signing in
|
|
|
286
286
|
session: cookies, storage and the browser identity it needs
|
|
287
287
|
foldrun logout forget this machine's key, and revoke it where allowed
|
|
288
288
|
foldrun whoami who you are on the platform: account, role, workspaces
|
|
289
|
+
foldrun signup status can a stranger sign up on the platform: free sign-up, paid sign-up, and the plans sold while paid is in effect — the open /api/signup, no key sent (--url, --json; exits 1 when it does not answer)
|
|
289
290
|
foldrun me the person this machine is signed in as: name, address, timezone (--json)
|
|
290
291
|
foldrun me name <first> [last] set your name (--clear for none) · foldrun me timezone <zone|auto> the zone you read times in
|
|
291
292
|
foldrun team who is in the account: role, the workspaces each may open, when they joined (--json)
|
package/docs/api.md
CHANGED
|
@@ -18,7 +18,7 @@ proof instead of a key: a token or signature (`/s/<token>`, `/api/hooks`,
|
|
|
18
18
|
`/api/billing/partner/…` (a storefront's signature),
|
|
19
19
|
`/api/billing/confirm`), the sign-in and recovery steps (`/api/auth/signup`,
|
|
20
20
|
`login`, `forgot`, `reset`, `verify`, `mfa/verify`, `session`, `/api/cli/login`,
|
|
21
|
-
`/api/cli/login/<id>`, `/api/cli/authorize` GET, `/api/oauth/callback`), `/api/healthz`, `/api/status`, `/api/status/history`, `/api/version` and `/api/openapi.json` — and an AI app's OAuth sign-in to `/api/mcp`: `/api/mcp/oauth/register` (open, as the protocol needs) and `/api/mcp/oauth/token` (its code and PKCE verifier, or its refresh token, are the proof).
|
|
21
|
+
`/api/cli/login/<id>`, `/api/cli/authorize` GET, `/api/oauth/callback`), `/api/healthz`, `/api/status`, `/api/status/history`, `/api/signup`, `/api/version` and `/api/openapi.json` — and an AI app's OAuth sign-in to `/api/mcp`: `/api/mcp/oauth/register` (open, as the protocol needs) and `/api/mcp/oauth/token` (its code and PKCE verifier, or its refresh token, are the proof).
|
|
22
22
|
|
|
23
23
|
```
|
|
24
24
|
Authorization: Bearer <api-key> # machines. Settings → API keys
|
|
@@ -471,7 +471,7 @@ X-Foldrun-Cli: 0.6.0 # the CLI released with this version (absent
|
|
|
471
471
|
|
|
472
472
|
| Route | Methods | |
|
|
473
473
|
|---|---|---|
|
|
474
|
-
| `/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 |
|
|
474
|
+
| `/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. Without an invite, a new account comes in by the first-account exception or free sign-up (`signup.open`) — decided again inside the write, so two first sign-ups at once make one owner; an invite needs no switch. A body with `plan` is refused (400): paid sign-up is not offered by this route yet. 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 |
|
|
475
475
|
| `/api/auth/login` | POST | `email`, `password`. Wrong passwords are limited per account: 8 a quarter hour from one caller when a trusted proxy names the caller (`FOLDRUN_TRUST_PROXY`), so a stranger failing as someone locks out only themselves, and 40 from every caller together, reaching which mails the person; with no caller address, 8 per account from anyone. A 429 carries `Retry-After` |
|
|
476
476
|
| `/api/auth/logout` | POST | ends the session |
|
|
477
477
|
| `/api/auth/session` | GET | who am I |
|
package/docs/cli.md
CHANGED
|
@@ -133,7 +133,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
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
135
|
| `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
|
-
| `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`, or
|
|
136
|
+
| `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
137
|
| `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` |
|
|
138
138
|
| `foldrun workspaces` | what exists here, what exists on the platform, which are both — also `new <name>`, and `rm <name>` (locally; `--platform --yes` deletes it there). `--json`: `{ platform, workspaces: [{ name, here, platform }], error? }`, exit 1 when the platform could not be read |
|
|
139
139
|
| `foldrun workspaces show <name>` | what is deployed in one workspace (`GET /api/workspaces/<name>`): its agents with model and description, its flows and how each fires, and its files counted by top-level folder. `--json` for the document |
|
|
@@ -150,6 +150,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
150
150
|
| `foldrun login <site> --url <address>` | a browser window to sign in to a site by hand; the session is stored for an agent |
|
|
151
151
|
| `foldrun logout` | forget this machine's key, and revoke it if `login` made it |
|
|
152
152
|
| `foldrun whoami` | who you are on the platform: account, role, which workspaces |
|
|
153
|
+
| `foldrun signup status` | can a stranger sign up on the platform, and how: **free** sign-up (an account without paying) open or closed, **paid** sign-up (choosing a plan — foldrun's hosted platform only, in effect only while payments are ready) open or closed, and while paid is open the plans it sells. Reads the open `GET /api/signup` — what foldrun.io's sign-up buttons read — and never sends a key, whatever `--url` names; the signed-in platform, `--url` / `FOLDRUN_URL`, or the default, dash.foldrun.io. `--json` prints the answer as is. Exits 1 when the platform does not answer or answers another shape. What each switch is SET to, and why paid is not in effect, is the operator console's |
|
|
153
154
|
| `foldrun team` | who is in the account (`GET /api/team`): each member's email, role (the owner marked), the workspaces they may open — a scoped key sees only the ones it shares — and when they joined. `--json` |
|
|
154
155
|
| `foldrun team invite [email]` | invite someone (`POST /api/team`): `--role viewer\|editor\|admin` (default editor), `--workspaces a,b` or `--all` (omitted: every workspace, unless you are scoped — then name them), `--no-send` to mail nothing. Without an address the link works for whoever has it. Prints the link once: it works one time, for seven days, and is shown only to you. `--json`. Like every `team` write, it is a person's: it works from your own `foldrun login` on this machine, never from a key made by hand, and it acts at the lower of that sign-in's role and yours now — an owner's sign-in here is an admin, so inviting, changing or removing an admin stays in Settings → Team |
|
|
155
156
|
| `foldrun team role <email\|id> <role>` | change a member's role to viewer, editor or admin (`PATCH /api/team/members/<id>`); the member by address (any case) or id. Their keys above the new role stop. Nobody changes their own role, and owner is transferred, not set |
|
|
@@ -279,7 +280,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
279
280
|
| `--note "<text>"` | `approve`: guidance the approved step reads in its prompt — "approve, but skip the Sydney batch". `reject`: the reason, recorded on the trace |
|
|
280
281
|
| `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `decide_approval`, `answer_question`, `message_run` or `stop_run` |
|
|
281
282
|
| `--yes` | skip the confirmation, deliberately: `approve`, `stop`, `deploy` (when it would delete files), and a bulk `stop` or `rerun`, `flow rotate-hook`, `flow draft`, `assistant`, `mcp disconnect`, `a2a cancel`, `history restore`, `restore`, `billing plan`, `repo deploy`/`merge`, `workspace set name`, and every delete — `runs rm`, `storage rm`, `storage unshare`, `source rm`, `secrets rm`, `keys revoke`, `workspaces rm`. Required when there is no terminal to ask; without it nothing is deleted |
|
|
282
|
-
| `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `assistant`, `backups requests`, `status --platform --history`, `team`, `secrets ls`, `triggers`, `storage ls --all`: the raw document |
|
|
283
|
+
| `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `assistant`, `backups requests`, `status --platform --history`, `signup status`, `team`, `secrets ls`, `triggers`, `storage ls --all`: the raw document |
|
|
283
284
|
| `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
|
|
284
285
|
| `--watch` | `invoke`: follow the run's trace here as it happens; the exit code is the run's |
|
|
285
286
|
| `--print` | `open`: print the URL, do not open it |
|
|
@@ -490,8 +491,8 @@ the same platform** — an agency looking after four customers keeps four,
|
|
|
490
491
|
and switches between them without pasting a key:
|
|
491
492
|
|
|
492
493
|
```sh
|
|
493
|
-
foldrun login --url https://
|
|
494
|
-
foldrun login --url https://
|
|
494
|
+
foldrun login --url https://dash.foldrun.io # as acme
|
|
495
|
+
foldrun login --url https://dash.foldrun.io # as beta, in a second browser
|
|
495
496
|
foldrun accounts # both, ● on the active one
|
|
496
497
|
foldrun use acme # from here on, acme
|
|
497
498
|
foldrun logs --profile beta --to leads # just this once, beta
|
|
@@ -525,7 +526,7 @@ foldrun keys create "alex's laptop" --role admin
|
|
|
525
526
|
The key is printed once. They send it to you; you store it as a profile:
|
|
526
527
|
|
|
527
528
|
```sh
|
|
528
|
-
foldrun login --url https://
|
|
529
|
+
foldrun login --url https://dash.foldrun.io --token <the key> --profile acme
|
|
529
530
|
```
|
|
530
531
|
|
|
531
532
|
The key carries the role it was minted with, so an `editor` key cannot
|
package/docs/self-hosting.md
CHANGED
|
@@ -77,7 +77,11 @@ whoever ran it (the token is `FOLDRUN_SETUP_TOKEN` in `~/foldrun/.env`, and
|
|
|
77
77
|
does nothing once the owner exists). With `FOLDRUN_BIND` set to one address
|
|
78
78
|
the link uses that address; from another machine, open it through the
|
|
79
79
|
tunnel the installer prints (`ssh -o ExitOnForwardFailure=yes -L …`), never
|
|
80
|
-
over plain http.
|
|
80
|
+
over plain http. After the owner, the install takes new accounts only on an
|
|
81
|
+
invite (Settings → Team) unless you open sign-up to strangers with
|
|
82
|
+
`FOLDRUN_OPEN_SIGNUP=1`; with it off, `/signup` says registration is closed
|
|
83
|
+
and `GET /api/signup` answers `{ "free": false, "paid": false, "plans": [] }`.
|
|
84
|
+
Then sign the CLI in and deploy:
|
|
81
85
|
|
|
82
86
|
```sh
|
|
83
87
|
npm install -g foldrun
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "19.1
|
|
3
|
+
"version": "19.2.1",
|
|
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",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"node": ">=22"
|
|
12
12
|
},
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@foldrun/core": "^17.0
|
|
14
|
+
"@foldrun/core": "^17.1.0"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
17
|
"bin",
|
package/src/commands.mjs
CHANGED
|
@@ -4422,7 +4422,9 @@ async function connect(positional, flags) {
|
|
|
4422
4422
|
|
|
4423
4423
|
// ---------------------------------------------------------------- login
|
|
4424
4424
|
|
|
4425
|
-
|
|
4425
|
+
// The hosted platform, when nothing names one (--url, FOLDRUN_URL, the
|
|
4426
|
+
// profile `foldrun login` last signed in to). Written once, here.
|
|
4427
|
+
const DEFAULT_PLATFORM = "https://dash.foldrun.io";
|
|
4426
4428
|
|
|
4427
4429
|
function openInBrowser(target) {
|
|
4428
4430
|
// A server-supplied address: only a web page, never a file, an app or a
|
|
@@ -5487,6 +5489,59 @@ async function platformStatusCmd(flags) {
|
|
|
5487
5489
|
return 0;
|
|
5488
5490
|
}
|
|
5489
5491
|
|
|
5492
|
+
/**
|
|
5493
|
+
* `foldrun signup status` — can a stranger sign up on this platform, and
|
|
5494
|
+
* how: free sign-up, paid sign-up, and the plans it sells while paid is in
|
|
5495
|
+
* effect. The open GET /api/signup the public site's buttons read; no key is
|
|
5496
|
+
* ever sent with it, whatever platform --url names. For an operator checking
|
|
5497
|
+
* what foldrun.io now sees after flipping a switch (the console shows each
|
|
5498
|
+
* switch as set and as in effect), or a self-hoster checking theirs.
|
|
5499
|
+
* Exits 1 when the platform does not answer or answers something else.
|
|
5500
|
+
*/
|
|
5501
|
+
async function signupCmd(positional, flags) {
|
|
5502
|
+
const verb = positional[0] ?? "status";
|
|
5503
|
+
if (verb !== "status") throw new Error(`signup: unknown verb "${verb}" — status`);
|
|
5504
|
+
const url = remoteUrl(flags) ?? DEFAULT_PLATFORM;
|
|
5505
|
+
let res;
|
|
5506
|
+
try {
|
|
5507
|
+
res = await remoteFetch(url, "/api/signup", {}, { seconds: timeoutSeconds(flags) });
|
|
5508
|
+
} catch (err) {
|
|
5509
|
+
const error = err instanceof Error ? err.message : String(err);
|
|
5510
|
+
if (flags.json === true) console.log(JSON.stringify({ url, error }, null, 2));
|
|
5511
|
+
else console.log(`\n ${c.red("✗")} ${url} did not answer (${error})\n`);
|
|
5512
|
+
return 1;
|
|
5513
|
+
}
|
|
5514
|
+
/** @type {any} */
|
|
5515
|
+
const body = await res.json().catch(() => null);
|
|
5516
|
+
const shaped = body && typeof body === "object" && typeof body.free === "boolean" && typeof body.paid === "boolean" && Array.isArray(body.plans);
|
|
5517
|
+
if (!res.ok || !shaped) {
|
|
5518
|
+
const error = !res.ok ? `/api/signup → HTTP ${res.status}` : "/api/signup answered something that is not { free, paid, plans }";
|
|
5519
|
+
if (flags.json === true) console.log(JSON.stringify({ url, error }, null, 2));
|
|
5520
|
+
else console.log(`\n ${c.red("✗")} ${error} — ${url}\n`);
|
|
5521
|
+
return 1;
|
|
5522
|
+
}
|
|
5523
|
+
if (flags.json === true) {
|
|
5524
|
+
console.log(JSON.stringify(body, null, 2));
|
|
5525
|
+
return 0;
|
|
5526
|
+
}
|
|
5527
|
+
const door = (open) => (open ? c.green("open") : c.dim("closed"));
|
|
5528
|
+
console.log(`\n ${c.bold("sign-up")} ${c.dim(url)}\n`);
|
|
5529
|
+
console.log(` free ${door(body.free)}`);
|
|
5530
|
+
console.log(` paid ${door(body.paid)}`);
|
|
5531
|
+
if (!body.free && !body.paid) console.log(`\n ${c.dim("new account registration is closed — invites still work")}`);
|
|
5532
|
+
if (body.plans.length) {
|
|
5533
|
+
console.log(`\n ${c.dim("plans")}`);
|
|
5534
|
+
for (const p of body.plans) {
|
|
5535
|
+
const price = p.price && typeof p.price.amount === "number" ? `${(p.price.amount / 100).toFixed(p.price.amount % 100 ? 2 : 0)} ${String(p.price.currency ?? "").toUpperCase()}/${p.price.interval ?? "month"}` : "—";
|
|
5536
|
+
console.log(` ${String(p.name ?? p.id).padEnd(10)} ${price.padEnd(14)} ${c.dim(`${p.credits ?? "?"} credits · ${p.vcpu ?? "?"} vCPU · ${p.memoryGiB ?? "?"} GiB${p.priority ? " · high-priority lane" : ""}`)}`);
|
|
5537
|
+
}
|
|
5538
|
+
} else if (body.paid) {
|
|
5539
|
+
console.log(`\n ${c.dim("no plans listed")}`);
|
|
5540
|
+
}
|
|
5541
|
+
console.log();
|
|
5542
|
+
return 0;
|
|
5543
|
+
}
|
|
5544
|
+
|
|
5490
5545
|
/**
|
|
5491
5546
|
* `foldrun status --platform --history [--days n]` — what the status page
|
|
5492
5547
|
* draws as bars: each component's uptime per day over the window (1–90,
|
|
@@ -14568,6 +14623,8 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
14568
14623
|
return logout(flags);
|
|
14569
14624
|
case "whoami":
|
|
14570
14625
|
return whoami(flags);
|
|
14626
|
+
case "signup":
|
|
14627
|
+
return signupCmd(positional, flags);
|
|
14571
14628
|
case "doctor":
|
|
14572
14629
|
return doctor(flags);
|
|
14573
14630
|
case "version":
|