cf-orbs 0.2.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
 
@@ -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.
 
@@ -202,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) |
@@ -272,7 +275,7 @@ To report a vulnerability, see [SECURITY.md](https://github.com/meirdick/cf-orbs
 
 ## Status and known gaps
 
-v0.2.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:
 

package/dist/commands/init.js

@@ -339,6 +339,10 @@ export async function runInit(ctx, o, steps) {
                     ui.step("control token: reusing .cf-orbs/control-token");
                 break;
             case "amp-token":
+                // No interactive name question here: say so if the name is a fallback, not given
+                if (s.source !== "prompt" &&
+                    (o.providerNameSource === "config" || o.providerNameSource === "default"))
+                    ui.warn(`provider name ${providerName} was not given explicitly; it must match the name in Amp Settings → Orbs (pass --provider-name <name> if it differs)`);
                 if (s.source === "env")
                     ampToken = checkAmpToken(ctx, (ctx.env.AMP_ORB_PROVIDER_TOKEN ?? "").trim());
                 else if (s.source === "file") {
@@ -355,7 +359,7 @@ export async function runInit(ctx, o, steps) {
                         : keep
                             ? "; Enter keeps the current one"
                             : "";
-                    const t = await askHidden(`Amp provider token (aop_live_…, not shown)${enter}: `);
+                    const t = await askHidden(`Amp provider token (aop_live_…, not shown; create or copy it in Amp Settings → Orbs → Add Provider)${enter}: `);
                     if (t === "" && o.noDeploy)
                         ui.step("amp token: not given; set it later (see the steps below)");
                     else if (t === "" && keep)
@@ -766,6 +770,15 @@ export function initOptions(ctx, existing) {
             existing?.providerName ??
             existing?.name ??
             "cf-orbs",
+        providerNameSource: flagString(ctx.args, "provider-name") !== undefined
+            ? "flag"
+            : ctx.env.AMP_ORB_PROVIDER_NAME !== undefined
+                ? "env"
+                : existing?.providerName !== undefined
+                    ? "saved"
+                    : existing?.name !== undefined
+                        ? "config"
+                        : "default",
     };
 }
 export async function initCommand(ctx) {

package/dist/config.js

@@ -307,7 +307,7 @@ export function validateInstance(v) {
 export function instanceMemoryMib(i) {
     if (typeof i === "object")
         return i.memoryMib;
-    return { lite: 256, "standard-1": 4096, "standard-2": 6144, "standard-3": 8192, "standard-4": 12288 }[i];
+    return { "standard-1": 4096, "standard-2": 6144, "standard-3": 8192, "standard-4": 12288 }[i];
 }
 /** fastTmpfsGb: 0-8, and at most the orb memory minus 3 GiB. Same rule as worker validateFastTmpfs. */
 export function validateFastTmpfs(v, instance) {

package/dist/index.js

@@ -30,7 +30,7 @@ export const COMMANDS = {
             "--provider cloudflare|external   where amp orb provider runs (default cloudflare)",
             "--token-file <file>              Amp provider token file (else AMP_ORB_PROVIDER_TOKEN, else prompt)",
             "--account-id <id>                Cloudflare account (else CLOUDFLARE_ACCOUNT_ID, else ask)",
-            "--provider-name <name>           Amp provider name, as in Amp Settings → Orbs (default cf-orbs)",
+            "--provider-name <name>           Amp provider name, as in Amp Settings → Orbs (else AMP_ORB_PROVIDER_NAME, saved name, config name, then cf-orbs)",
             "--subdomain <name>               workers.dev subdomain to register if the account has none",
             "--vcpu <1|2|3|4>                 orb size: N vCPU, N x 3 GiB, 20 GB disk (default 4; 2 is cheaper)",
             "--name <name>                    Worker name (default cf-orbs; a second install needs another)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cf-orbs",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Run Amp orbs on Cloudflare Containers: self-hosted orb provider, one command to install.",
   "license": "Apache-2.0",
   "type": "module",

package/templates/cf-orbs.config.example.jsonc

@@ -5,7 +5,7 @@
   "name": "cf-orbs",
 
   // Orb size. One size per install: Amp sends no size to the provider.
-  // Custom: vcpu 1-4, memoryMib up to 12288 and at least 3072 per vCPU, diskMb 8000-20000.
+  // Custom: vcpu 1-4 (fractions allowed), memoryMib up to 12288 and at least 3072 per vCPU, diskMb 8000-20000.
   // Or a named type: "standard-1" .. "standard-4". "lite" and "basic" are too small for the orb image.
   // Default 4 vCPU, 12 GiB, 20 GB. `cf-orbs init --vcpu N` writes N vCPU, N x 3 GiB, 20 GB (--vcpu 2 is cheaper).
   "instance": { "vcpu": 4, "memoryMib": 12288, "diskMb": 20000 },
@@ -53,4 +53,18 @@
 
   // Enable wrangler containers ssh for orbs (debug only).
   "debugSsh": false
+
+  // Turn on the exec and bench routes. Only for the substrate benchmark: the control token can then run
+  // commands in orbs. true or false.
+  // "debugExec": false,
+
+  // Minutes an orb may sit idle before the container stops. 5-360.
+  // "inactivityTimeoutMinutes": 15,
+
+  // Seconds between watchdog checks of an orb. 10-3600, and shorter than inactivityTimeoutMinutes.
+  // "alarmSeconds": 60,
+
+  // Digest of the Amp orb image the "orb" image is built from. Used for log lines only.
+  // Must look like sha256:<64 hex digits>.
+  // "ampImageDigest": "sha256:378c5e2188f00960eca36dc806aa04e1cacd92c2341665bcdf4692326c462d6d"
 }

package/templates/dispatch/dispatch.sh

@@ -1,5 +1,5 @@
 #!/bin/sh
-# cf-orbs dispatch program. `amp orb provider` runs it once per job (D11, D12).
+# cf-orbs dispatch program. `amp orb provider` runs it once per job.
 #
 # Input (env, from Amp): ORB_OPERATION ORB_ID ORB_IMAGE ORB_SNAPSHOT_ID ORB_TOKEN AMP_URL
 # Input (env, from cf-orbs):
@@ -190,7 +190,7 @@ redact() { CFO_CTL=$CTL_TOKEN awk "$REDACT_AWK"; }
 say() { printf '%s\n' "$*" | redact; }
 
 # fail <message> [exit code]. One final line on stdout and stderr. Worker errors already start
-# with "Failed: "; drop it so the line has one prefix (D12).
+# with "Failed: "; drop it so the line has one prefix.
 fail() {
   msg=$1
   while :; do
@@ -223,7 +223,7 @@ case $OP in
   *) fail "unknown ORB_OPERATION '$(clean "$OP")' — fix: update cf-orbs (npx cf-orbs@latest deploy)" 2 ;;
 esac
 
-# Same rule as the server (D2): ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$
+# Same rule as the server: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$
 orb_ok=1
 case $ORB in
   "" | [!A-Za-z0-9]* | *[!A-Za-z0-9_-]*) orb_ok=0 ;;

package/templates/image/Dockerfile

@@ -1,4 +1,4 @@
-# cf-orbs orb image (D4). Built by `cf-orbs deploy` (wrangler) and stored under the image key "orb".
+# cf-orbs orb image. Built by `cf-orbs deploy` (wrangler) and stored under the image key "orb".
 #
 # Why a digest pin and not :latest
 #   A snapshot only restores onto the image it was taken from. A moving tag gives a new image on the
@@ -10,7 +10,7 @@
 #   The base image has no init and its CMD (python3) exits at once. tini is PID 1, keeps the container
 #   up with `sleep infinity`, and reaps the processes that cf-orbs starts with setsid (amp orb bootstrap
 #   and its children). -s makes tini a subreaper, so orphans of those processes are reaped too.
-#   tini is pinned to one Debian version so that a rebuild without cache gives the same layer (R18).
+#   tini is pinned to one Debian version so that a rebuild without cache gives the same layer.
 #   If apt cannot find that version any more, bump it and treat the result as a new image.
 #
 # How to add toolchains

package/templates/provider/Dockerfile

@@ -1,4 +1,4 @@
-# cf-orbs provider image (D18). Runs `amp orb provider /app/dispatch.sh` under tini.
+# cf-orbs provider image. Runs `amp orb provider /app/dispatch.sh` under tini.
 # Build context is the repo root (wrangler image entry: build_context ".."):
 #   docker build -f provider/Dockerfile -t cf-orbs-provider .
 FROM node:24-bookworm-slim@sha256:c86ecead9e55a5210ac1727de38a4ca840bf03dcaf34dc9749addbf383b1920c
@@ -6,7 +6,7 @@ FROM node:24-bookworm-slim@sha256:c86ecead9e55a5210ac1727de38a4ca840bf03dcaf34dc
 # Pinned Amp CLI. Bump with Renovate or by hand; the provider must match Amp's job protocol.
 ARG AMP_CLI_VERSION=0.0.1793390435-g08e9ec
 
-# curl: dispatch.sh (D12). tini: PID 1 that forwards signals and reaps children.
+# curl: dispatch.sh. tini: PID 1 that forwards signals and reaps children.
 RUN apt-get update \
   && apt-get install -y --no-install-recommends curl ca-certificates tini \
   && rm -rf /var/lib/apt/lists/*

package/templates/provider/entry.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# cf-orbs provider entry (D18). Runs `amp orb provider <dispatch>` in a loop.
+# cf-orbs provider entry. Runs `amp orb provider <dispatch>` in a loop.
 # Output is redacted, then written to stdout and to the log file. The log is capped.
 # Env:
 #   AMP_ORB_PROVIDER_TOKEN  required. Read by amp; never printed.

package/templates/worker/src/api.ts

@@ -18,7 +18,7 @@ import { type Env, orbDoName, PROVIDER_DO_NAME, REGISTRY_DO_NAME } from "./env";
 import { BENCH_ORB_RE, type BenchStartRequest, parseBenchStart } from "./orb/bench";
 import { restartProvider } from "./provider-restart";
 
-export const API_VERSION = "0.1.0";
+export const API_VERSION = "0.2.2";
 
 /** D2. Amp sends `amp-<thread id>`. Never starts with `_` or `.`, so it cannot look like an internal name. */
 export const ORB_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;

package/templates/worker/src/core/config.ts

@@ -5,6 +5,7 @@ import {
   DEFAULT_CONFIG,
   type InstanceSpec,
   MAX_PREWARM,
+  type OrbInstanceSpec,
   type ProjectSnapshotRefresh,
   type ProviderConfig,
 } from "./types";
@@ -37,9 +38,9 @@ function num(v: unknown, name: string, min: number, max: number, integer = true)
   return v;
 }
 
-export function validateInstance(v: unknown): InstanceSpec {
+export function validateInstance(v: unknown): OrbInstanceSpec {
   if (typeof v === "string") {
-    if ((NAMED as readonly string[]).includes(v)) return v as InstanceSpec;
+    if ((NAMED as readonly string[]).includes(v)) return v as OrbInstanceSpec;
     if (v === "lite" || v === "basic" || v === "dev") {
       fail(
         `instance ${v} is too small for the orb image`,

package/templates/worker/src/core/types.ts

@@ -49,7 +49,7 @@ export interface SnapshotHandle {
   id: string; // Cloudflare snapshot id
   size: number; // bytes reported by snapshotContainer
   imageKey: string; // key in images map the snapshot was taken from
-  instance: InstanceSpec;
+  instance: OrbInstanceSpec;
   createdAt: string; // ISO
   lastRestoredAt?: string; // ISO; set on every successful restore. Expiry = max(createdAt, lastRestoredAt) + 30 d (D7)
   name?: string;
@@ -70,6 +70,7 @@ export interface SpawnEntry {
 /** OrbRecord.spawns keeps this many entries, oldest first. */
 export const SPAWN_HISTORY = 10;
 
+/** Any Cloudflare Containers instance size. "lite" (256 MiB) is used only by the provider container. */
 export type InstanceSpec =
   | "lite"
   | "standard-1"
@@ -78,6 +79,9 @@ export type InstanceSpec =
   | "standard-4"
   | { vcpu: number; memoryMib: number; diskMb: number };
 
+/** An orb size. "lite" is too small for the orb image, so config validation rejects it. */
+export type OrbInstanceSpec = Exclude<InstanceSpec, "lite">;
+
 /** Per-orb record in OrbSession storage under key "orb". */
 export interface OrbRecord {
   /** Schema version (D13). Old and new Worker code share storage; a missing v reads as 1. */
@@ -85,7 +89,7 @@ export interface OrbRecord {
   orbId: string;
   state: OrbState;
   imageKey: string;
-  instance: InstanceSpec;
+  instance: OrbInstanceSpec;
   handle?: SnapshotHandle; // per-orb snapshot (last pause or checkpoint)
   bootstrapTokenSha?: string; // first 16 hex of sha256(ORB_TOKEN) for the running bootstrap
   awakeSince?: string;
@@ -136,7 +140,7 @@ export type ProjectSnapshotRefresh = "off" | "on-change";
 
 /** Provider-level configuration, derived from cf-orbs.config.jsonc and passed as Worker vars (JSON string in CF_ORBS_CONFIG). */
 export interface ProviderConfig {
-  instance: InstanceSpec; // default { vcpu: 4, memoryMib: 12288, diskMb: 20000 }
+  instance: OrbInstanceSpec; // default { vcpu: 4, memoryMib: 12288, diskMb: 20000 }
   maxRunning: number; // default 20
   maxAwakeHours: number; // default 12
   checkpointMinutes: number; // default 0 = off