cf-orbs 0.1.1 → 0.2.2

package/README.md

@@ -2,21 +2,24 @@
 
 Run [Amp](https://ampcode.com) orbs on your own Cloudflare account. cf-orbs is a self-hosted Amp orb provider built on Cloudflare Containers. You install it with one command.
 
+Docs: [cf-orbs-site.mdick85.workers.dev/docs](https://cf-orbs-site.mdick85.workers.dev/docs/)
+
 Community project. Not affiliated with Cloudflare or Amp (Sourcegraph). "Cloudflare" and "Amp" are trademarks of their owners.
 
 ## Why cf-orbs
 
-Measured against Amp-hosted orbs and Amp's reference providers for Docker, E2B and Vercel, same prompt, same project, same night (2026-10-31, [full table](https://cf-orbs-site.mdick85.workers.dev/#compare), [method](https://github.com/meirdick/cf-orbs/blob/main/docs/benchmarks.md)):
+Amp's self-hosted orbs work like this: you provide the compute, and Amp turns it into orbs. cf-orbs makes your Cloudflare account that compute. You keep the same Amp threads and the same orb experience, on machines you own.
+
+- **Your account.** Orbs, snapshots and logs stay in your Cloudflare account. The provider connects out to Amp. Nothing connects in.
+- **No server to run.** One CLI, no cluster, no extra API keys. Cloudflare runs the machines.
+- **Your image.** Orbs start from your own image and toolchain (`image/Dockerfile`).
+- **Your bill.** You pay Cloudflare. A paused orb has no compute charge.
+- **New threads start ready.** Repo setup runs once. Each new thread then starts from that project snapshot, with your dependencies already installed.
+- **Recovers by itself.** A lost orb comes back and the agent runs the failed tool call again. Paused orbs restore after an image rebuild.
 
-- **Fast new threads.** Project snapshots skip `.agents/setup`: about 12 s of orb setup before the first turn, against 36-45 s for the E2B and Vercel reference scripts, which rebuild the repo every thread.
-- **Fast wake.** Warm pause keeps the orb and its Amp executor alive for 10 min after Amp pauses it (snapshot taken first, `warmMinutes` to change). A follow-up in that window runs its first tool in 0.3-0.5 s; Amp-hosted takes 0.85 s, a cold restore 1.5-2 s plus process start.
-- **Fast network.** git clone 0.26 s, npm install of express 7.7 s; Amp-hosted a1.small 0.54 s and 15.2 s; E2B 0.44 s and 10.1 s.
-- **Same interactive speed.** Tool round trips on a live orb are 0.8-0.9 s on every provider.
-- **Reliable.** 10 of 10 threads in every benchmark round. A lost orb comes back in 22 s and the agent retries. Paused orbs restore after an image rebuild.
-- **Cheapest cloud option at this size.** About $0.11/h running idle and $0.17/h at 20% CPU for 4 vCPU / 12 GiB / 20 GB; no compute charge while paused (snapshot storage has no published rate yet). Amp-hosted a1.small is $0.17/h for 2 CPU / 4 GiB; E2B about $0.33/h for 4 vCPU / 8 GiB.
-- **Yours.** One CLI, no cluster, no extra API keys. Orbs, snapshots and logs stay in your Cloudflare account.
+Benchmarked as fast or faster than Amp-hosted orbs on first response and installs ([benchmarks](https://cf-orbs-site.mdick85.workers.dev/benchmarks), [method](https://github.com/meirdick/cf-orbs/blob/main/docs/benchmarks.md#method)).
 
-Known limits, measured: writes of new data on the root disk are slower (512 MB with fsync 0.9 s with `hugePages`, was 1.3 s; Amp-hosted 0.6 s; use `/mnt/fast` for caches, see `fastTmpfsGb`); 4 vCPU / 12 GiB / 20 GB per orb; the first spawn on a new Cloudflare host pulls the 1.8 GB image (40-50 s, then cached). Details in [docs/05](https://github.com/meirdick/cf-orbs/blob/main/docs/benchmarks.md).
+Good to know: a paused orb keeps its files, not running processes (Cloudflare saves the disk only). One orb is at most 4 vCPU, 12 GiB memory and 20 GB disk.
 
 ## What it is
 
@@ -35,7 +38,7 @@ When Amp pauses an orb, cf-orbs saves the disk as a snapshot and stops the conta
 | You need | Check |
 | --- | --- |
 | Node 22 or later (wrangler 4 needs it) | `node --version` |
-| Docker, running. wrangler builds the orb image on your machine | `docker info` |
+| Docker, running. wrangler builds the orb image on your machine (not for the [Workers Builds path](#install-without-docker-workers-builds-preview)) | `docker info` |
 | A Cloudflare account on **Workers Paid** ($5/month; Containers need it) | Dashboard → Workers & Pages → Plans |
 | wrangler logged in to that account | `npx wrangler login`, then `npx wrangler whoami` |
 | An Amp provider token (`aop_live_…`) | Amp → Settings → Orbs → Add Provider. Note the provider name you type there |
@@ -49,7 +52,7 @@ mkdir my-orbs && cd my-orbs
 npx cf-orbs init --provider-name <name from Amp>
 ```
 
-`init` asks for the Amp provider token. It does not show what you type, and the token does not go into your shell history.
+`init` asks for the Amp provider token. The prompt names the Amp page where you create it. It does not show what you type, and the token does not go into your shell history.
 
 Measured on 2026-10-30 in an empty directory: **4 min 41 s** from `init` to a running provider. That includes the push of the 1.8 GB orb image (the whole deploy took 247 s). A slow uplink takes longer. The Cloudflare registry sometimes times out on a large push, or answers `Unauthorized` after image preparation. `init` retries both automatically, up to 3 times, and keeps the layers that it already pushed.
 
@@ -95,6 +98,38 @@ node cli/bin/cf-orbs.js init ../my-orbs --provider-name <name>   # asks for the
 
 Then use `node <repo>/cli/bin/cf-orbs.js` wherever this README says `cf-orbs`, with `--dir ../my-orbs` or from inside that directory.
 
+### Install without Docker (Workers Builds, preview)
+
+No Docker on your machine? `init --no-deploy` makes a git repo and the Worker with its secrets, but does not deploy. You push the repo to GitHub or GitLab and connect it in the Cloudflare dashboard. Workers Builds then builds both images in your account and deploys on each push. Measured: first build 10.6 min, upgrade 5.6 min, plus 2-4 min in the queue.
+
+```sh
+npx cf-orbs init --no-deploy --provider-name <name from Amp> --token-file <file>
+```
+
+It prints the dashboard settings to use. Full procedure and caveats: [docs/install-workers-builds.md](https://github.com/meirdick/cf-orbs/blob/main/docs/install-workers-builds.md). This is a preview: the default install above (local Docker) and all defaults do not change.
+
+### What init validates
+
+Before the deploy, `init` stops with one `Failed: … — fix: …` line when:
+
+- Node is older than 22.
+- Docker does not answer `docker info` (not checked with `--no-deploy`).
+- wrangler is not logged in, sees no account, or sees several and you gave no `--account-id` (or an id that `wrangler whoami` does not list).
+- There is no Amp token, or it is empty or has spaces (a token without `aop_live_` gives a warning). With `--no-deploy` the token is optional.
+- `cf-orbs.config.jsonc` is not valid: unknown keys, sizes out of range, a bad name or image key.
+- An extra image key has no `image/<key>.Dockerfile`.
+- The account has no workers.dev subdomain and you gave no `--subdomain` (in a terminal, `init` asks for one).
+- `wrangler containers list` fails with a clear plan or login error (Workers Paid is needed). Any other error is a warning.
+
+After the deploy, `init` checks that `/v1/health` answers, that `/v1/status` accepts the control token, that at least one prewarm instance starts from the new image (self-test; skipped when `prewarm` is 0, and with `--no-deploy` until a build has run), and that the provider runs for 15 s with no token rejection and no second provider on the token.
+
+`cf-orbs doctor` also checks the project files, in every mode:
+
+- `image/Dockerfile` (and each extra image key) and the provider image use `FROM <image>@sha256:<digest>`.
+- `debugExec` is `false` (WARN when `true`).
+- No `aop_live_` token and no control token value is in a file that git tracks (SKIP outside a git repo).
+- `--no-deploy` projects only: `.gitignore` keeps out `.cf-orbs/control-token` and `.cf-orbs/state.json`, and `package.json` pins the wrangler version that cf-orbs uses.
+
 ## What you get
 
 - Orbs that run on your Cloudflare account. The repo checkout, build output and saved disks stay there.
@@ -149,7 +184,7 @@ Example: 120 awake hours a month at 20% CPU costs about $27.50 a month in total
 
 | Command | Does |
 | --- | --- |
-| `cf-orbs init [dir]` | Scaffold, deploy and check a provider. Flags: `--provider cloudflare\|external`, `--token-file`, `--account-id`, `--provider-name`, `--subdomain`, `--vcpu <1\|2\|3\|4>` |
+| `cf-orbs init [dir]` | Scaffold, deploy and check a provider. Flags: `--provider cloudflare\|external`, `--token-file`, `--account-id`, `--provider-name`, `--subdomain`, `--vcpu <1\|2\|3\|4>`, `--name <worker>`, `--no-deploy` (preview: [Workers Builds](https://github.com/meirdick/cf-orbs/blob/main/docs/install-workers-builds.md), no Docker) |
 | `cf-orbs status [orb]` | Install status (provider, awake orbs, snapshots), or one orb |
 | `cf-orbs logs <orb>` | Redacted bootstrap log of one orb. `--lines N` (default 200) |
 | `cf-orbs logs --provider` | Redacted provider log (last 20 lines) |
@@ -170,7 +205,7 @@ Every command takes `--json`, `--dir <project>` and `--non-interactive`. Orb ids
 | Key | Default | Meaning |
 | --- | --- | --- |
 | `name` | `cf-orbs` | Worker name. A second install needs another name |
-| `instance` | `{vcpu: 4, memoryMib: 12288, diskMb: 20000}` | Orb size: custom (1-4 vCPU, at least 3 GiB per vCPU, up to 12 GiB, 8-20 GB disk) or `standard-1`..`standard-4`. `init --vcpu N` writes `{vcpu: N, memoryMib: N*3072, diskMb: 20000}` |
+| `instance` | `{vcpu: 4, memoryMib: 12288, diskMb: 20000}` | Orb size: custom (1-4 vCPU, fractions allowed, at least 3 GiB per vCPU, up to 12 GiB, 8-20 GB disk) or `standard-1`..`standard-4`. `init --vcpu N` writes `{vcpu: N, memoryMib: N*3072, diskMb: 20000}` |
 | `maxRunning` | 20 | Cap on awake orbs. The next spawn fails with a clear message |
 | `maxAwakeHours` | 12 | The watchdog pauses an orb that is awake longer than this |
 | `checkpointMinutes` | 0 (off) | Snapshot an awake orb with changes every N minutes (15 or more) |
@@ -240,11 +275,11 @@ To report a vulnerability, see [SECURITY.md](https://github.com/meirdick/cf-orbs
 
 ## Status and known gaps
 
-v0.1. The control plane, dispatch program, provider host and CLI are built and unit tested. On 2026-10-30 a real Amp thread ran end to end on a fresh install: spawn from the image, setup, pause with a project snapshot, wake from the snapshot in 2.3 s, first answer 41 s after the message.
+v0.2.2. The control plane, dispatch program, provider host and CLI are built and unit tested. On 2026-10-30 a real Amp thread ran end to end on a fresh install: spawn from the image, setup, pause with a project snapshot, wake from the snapshot in 2.3 s, first answer 41 s after the message.
 
 Known gaps:
 
-- `init` has no orb self-test yet, and no Workers Paid check before the first deploy (a Free account finds out from the deploy error).
+- The plan check before the first deploy is best effort: it asks wrangler to list Containers and stops only on a clear plan or login error. Any other error is a warning, and a Free account may still find out from the deploy error.
 - Paused orbs restore after an image rebuild. A restored disk keeps its old content; new image content reaches only orbs started from the image.
 - Orb lost mid-turn: Amp spawns the orb again and the agent runs the failed tool call again. The disk is kept; running processes and shell state are lost.
 - Not tested yet: the provider's memory on `lite` over 24 h, restore after the source image is deleted from the registry, the Desktop pane, and Docker inside an orb. Snapshot storage has no published price (beta).
@@ -263,6 +298,7 @@ Method, results and costs: [docs/benchmarks.md](https://github.com/meirdick/cf-o
 | Doc | Covers |
 | --- | --- |
 | [AGENTS.md](https://github.com/meirdick/cf-orbs/blob/main/AGENTS.md) | Install guide for an AI agent at a terminal |
+| [Install without Docker](https://github.com/meirdick/cf-orbs/blob/main/docs/install-workers-builds.md) | Preview: Workers Builds builds and deploys from a git repo |
 | [Provider host](https://github.com/meirdick/cf-orbs/blob/main/provider/README.md) | Cloudflare-hosted vs external provider, token rotation |
 | [Orb image](https://github.com/meirdick/cf-orbs/blob/main/image/README.md) | The pinned image, toolchains, why snapshots are tied to it |
 | [Dispatch](https://github.com/meirdick/cf-orbs/blob/main/dispatch/README.md) | The program Amp runs per job, and its protocol |

package/dist/commands/deploy.js

@@ -12,7 +12,8 @@ import { deployWithRetry, lastErrorLine, makeWrangler } from "../wrangler.js";
 export async function deployProject(ctx, input) {
     const { ui, paths } = ctx;
     const { config, state } = input;
-    await materialize(paths, { templates: ctx.templates });
+    const git = state.mode === "git";
+    await materialize(paths, { templates: ctx.templates, git });
     const missing = missingDockerfiles(paths, config);
     if (missing.length > 0) {
         throw new CliError(`image Dockerfile missing: ${missing.join(", ")}`, "create it, or remove its key from images in cf-orbs.config.jsonc");
@@ -38,7 +39,8 @@ export async function deployProject(ctx, input) {
         ...state,
         url,
         workerName: config.name,
-        mode: config.providerHost,
+        // git mode stays git mode: Workers Builds still deploys from the repo
+        mode: git ? "git" : config.providerHost,
         deployedAt: new Date(ctx.now()).toISOString(),
         cliVersion: await cliVersion(),
     });

package/dist/commands/doctor.js

@@ -1,9 +1,11 @@
-// cf-orbs doctor: PASS/FAIL per check with a one-line fix, plus INFO hints that never fail. Read-only: never starts a provider or an orb.
+// cf-orbs doctor: PASS/FAIL per check with a one-line fix, plus INFO hints and WARN lines that never fail.
+// Read-only: never starts a provider or an orb.
 import { existsSync } from "node:fs";
 import { collectImageKeys, expectOk, providerInfo } from "../api.js";
 import { CONFIG_FILE, loadConfig, orbImageKeys } from "../config.js";
 import { connect } from "../connect.js";
 import { CliError, toFailedLine } from "../errors.js";
+import { fileChecks } from "../file-checks.js";
 import { fileMode, readState } from "../project.js";
 import { classifyDeployFailure, lastErrorLine, makeWrangler } from "../wrangler.js";
 import { AMP_CACHE_HINT } from "./snapshots.js";
@@ -77,6 +79,10 @@ export async function runDoctor(ctx) {
     }
     else
         checks.push(pass("control token", "present, mode 600"));
+    checks.push(...(await fileChecks(ctx.run, ctx.paths, config, {
+        git: state.mode === "git",
+        templates: ctx.templates,
+    })));
     const name = config?.name ?? state.workerName ?? "cf-orbs";
     const w = makeWrangler(ctx.run, { accountId: state.accountId });
     const d = await w.run(["deployments", "list", "--json", "--name", name], { timeoutMs: 60_000 });
@@ -106,20 +112,24 @@ export async function runDoctor(ctx) {
         checks.push(failed("health", e));
     }
     let status;
+    // git mode: Workers Builds deploys, so the fix is the build, not cf-orbs deploy
+    const apiFailed = (n, e) => state.mode === "git" && e instanceof CliError
+        ? failed(n, new CliError(e.cause_, `wait for the Workers Builds build to finish (Workers & Pages → ${name} → Deployments), or open its build log`))
+        : failed(n, e);
     if (api) {
         try {
             expectOk(await api.get("/v1/health"), "health");
             checks.push(pass("health", `${api.url}/v1/health ok`));
         }
         catch (e) {
-            checks.push(failed("health", e));
+            checks.push(apiFailed("health", e));
         }
         try {
             status = expectOk(await api.get("/v1/status"), "status");
             checks.push(pass("status", "/v1/status ok (control token accepted)"));
         }
         catch (e) {
-            checks.push(failed("status", e));
+            checks.push(apiFailed("status", e));
         }
     }
     // Names only: wrangler secret list never returns values.