cf-orbs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,11 @@
+cf-orbs
+Copyright 2026 Meir Dick
+
+This product includes software patterns adapted from cloudflare/sandbox-sdk
+(Apache-2.0, https://github.com/cloudflare/sandbox-sdk): the setsid + boot_id
+background-process guard, the per-object exclusive operation queue, and the
+auto-save alarm loop.
+
+cf-orbs is a community project. It is not affiliated with Cloudflare, Inc. or
+with Sourcegraph, Inc. (Amp). "Cloudflare" and "Amp" are trademarks of their
+respective owners.

package/README.md

@@ -1,3 +1,276 @@
-# Temporary Holding Version
+# cf-orbs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+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)):
+
+- **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.
+
+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).
+
+## What it is
+
+An Amp orb is the machine where an Amp agent runs its tools: it clones your repo, runs commands and edits files. Amp runs orbs on its own servers by default. With a self-hosted provider, the orbs run on your infrastructure instead.
+
+cf-orbs makes each orb a Cloudflare Container: a microVM with its own kernel, network and disk, started from Amp's orb image. It has three parts, all in your Cloudflare account:
+
+- **A Worker** (`cf-orbs`) with Durable Objects. It starts, pauses and deletes orbs and keeps track of their snapshots.
+- **A provider container.** It runs `amp orb provider`, which takes orb jobs from Amp over an outbound connection.
+- **The orbs.** One container per Amp thread.
+
+When Amp pauses an orb, cf-orbs saves the disk as a snapshot and stops the container, so a paused orb has no compute charge. The next message restores the disk. Amp project snapshots work too: a new thread on a known repo starts from the disk that Amp already set up.
+
+## Prerequisites
+
+| 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` |
+| 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 |
+
+A personal provider needs no workspace admin. Make it in your personal Amp settings.
+
+## Quick start
+
+```sh
+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.
+
+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.
+
+What `init` does:
+
+1. Checks Node, Docker, the wrangler login and the account.
+2. Writes `cf-orbs.config.jsonc`, `image/Dockerfile` and `.cf-orbs/` (generated files, the control token and state).
+3. Registers a workers.dev subdomain if the account has none (it asks for a name, or takes `--subdomain`).
+4. Runs `wrangler deploy`: builds and pushes the orb image and the provider image, then deploys the Worker.
+5. Checks `/v1/health` and `/v1/status`.
+6. Starts the provider and waits until it runs for 15 s with a clean log.
+7. Prints a command to try:
+
+```sh
+amp -ox "hello from cf-orbs" --orb-provider <name>
+```
+
+The name after `--orb-provider` must match the provider name in Amp Settings. In the Amp app, pick the provider under **Self-Hosted** when you start a thread.
+
+`init` is safe to run again. It keeps the control token, and it keeps the Amp token secret unless you give a new one.
+
+Non-interactive (CI or an agent): put the token in a file with mode 600 and pass `--token-file`. In CI, `AMP_ORB_PROVIDER_TOKEN` from a secret store also works.
+
+```sh
+npx cf-orbs init --non-interactive --token-file <file> --provider-name <name> --subdomain <name> \
+  --account-id <id>   # only if wrangler sees more than one account
+```
+
+Orb size: `init` writes 4 vCPU, 12 GiB, 20 GB disk. For a cheaper orb add `--vcpu 2` (2 vCPU, 6 GiB, about half the memory cost). `--vcpu <1|2|3|4>` writes N vCPU and N x 3 GiB. For any other size, edit `instance` in `cf-orbs.config.jsonc`.
+
+An AI agent that installs cf-orbs for you can follow [AGENTS.md](https://github.com/meirdick/cf-orbs/blob/main/AGENTS.md).
+
+### From a clone
+
+To run the CLI from source (for development, or to try a change):
+
+```sh
+git clone https://github.com/meirdick/cf-orbs && cd cf-orbs
+npm ci && npm run build -w cli
+mkdir ../my-orbs
+node cli/bin/cf-orbs.js init ../my-orbs --provider-name <name>   # asks for the token
+```
+
+Then use `node <repo>/cli/bin/cf-orbs.js` wherever this README says `cf-orbs`, with `--dir ../my-orbs` or from inside that directory.
+
+## What you get
+
+- Orbs that run on your Cloudflare account. The repo checkout, build output and saved disks stay there.
+- One orb size per install. Default: 4 vCPU, 12 GiB memory, 20 GB disk. Set it with `init --vcpu` or in `cf-orbs.config.jsonc`.
+- Pause and resume through disk snapshots, and Amp project snapshots for fast new threads.
+- A watchdog: it pauses an orb that stays awake longer than `maxAwakeHours` (default 12) and caps awake orbs at `maxRunning` (default 20).
+- `status`, `logs` and `doctor` commands. Every failure is one line: `Failed: <cause> — fix: <what to do>`.
+
+## Pause and resume
+
+Amp decides when an orb pauses: after the agent is idle and nobody interacts with the thread for about 20 minutes (we saw 20-25 min). An archived thread pauses too. A deleted thread deletes its orb.
+
+On pause, cf-orbs stops the Amp processes, takes a snapshot of the disk and stops the container. On the next message, Amp sends a spawn and cf-orbs restores the disk. Measured: spawn from a snapshot in 2.3 s (container ready in 0.6 s).
+
+| Kept | Lost |
+| --- | --- |
+| Files, the repo, installed packages, build caches (everything on the disk) | Running processes: dev servers, watchers, terminal sessions |
+| | Memory |
+
+Warm pause (`warmMinutes`, default 10): cf-orbs saves the disk at the pause but keeps the container and Amp's processes running for 10 more minutes. A message in that time reuses them: no restore, no restart. After that the orb stops. A warm orb counts toward `maxRunning` and is billed like an awake orb. `cf-orbs status` shows `warm` and the time left.
+
+Amp runs `.agents/resume` on wake, and portal services restart when you open them. Amp-hosted orbs keep memory across a pause; cf-orbs does not.
+
+Other things to know:
+
+- A paused orb can wake when somebody views its thread, with no new message. It pauses again later.
+- A snapshot is kept for 30 days after its last restore. An orb paused longer than that starts fresh, and Amp sets up the repo again.
+- Each pause makes a new snapshot, and storage is billed. `cf-orbs snapshots prune` lists the old ones that no orb uses; `--yes` deletes them through `wrangler containers images delete` (works, but Cloudflare does not document it). `cf-orbs status` shows `prunable: N (X GB)`.
+- Work done after the last pause can be lost if Cloudflare stops a container without warning. To limit that, set `checkpointMinutes` (15 or more) to snapshot awake orbs that have changes.
+- The restore is lazy. The first read of a large build cache after a wake is slower than later reads (about 230 MB/s).
+- A project snapshot goes stale after an Amp CLI release (each new thread then spends 4-5 s on the amp update) or after a `cf-orbs deploy` with a new image. With `projectSnapshotRefresh: "on-change"`, cf-orbs checks for this when a new thread starts from the snapshot. If it is stale, cf-orbs forgets the mapping (at most once per project per 24 h), so the next new thread boots the image and Amp runs setup.
+- This is off by default because cf-orbs never starts threads or orbs for it, so nothing extra shows in your Amp UI. Also, Amp does not always save a new snapshot after a forget. Until it does, each new thread runs setup, and `cf-orbs status` shows the snapshot as stale.
+- To do it by hand: delete the cached snapshot in Amp → Orb Settings → Snapshots, then run `cf-orbs snapshots forget --all-project`.
+
+## Costs
+
+Rates: [Cloudflare Containers pricing](https://developers.cloudflare.com/containers/platform/pricing/) and [Amp orb pricing](https://ampcode.com/docs/orbs/sizes-and-costs). Measured speed and cost: [docs/benchmarks.md](https://github.com/meirdick/cf-orbs/blob/main/docs/benchmarks.md).
+
+| Item | Cost (USD) |
+| --- | --- |
+| Workers Paid plan | $5.00/month |
+| Provider container (`lite`, always on) | ~$2.01/month |
+| Default orb (4 vCPU, 12 GiB, 20 GB), awake | $0.113/h fixed + CPU: ~$0.171/h at 20% CPU, ~$0.401/h at 100% |
+| Orb with `--vcpu 2` (2 vCPU, 6 GiB, 20 GB), awake | $0.059/h fixed + CPU: ~$0.088/h at 20% CPU, ~$0.203/h at 100% |
+| Paused orb | No compute charge. Snapshot storage price is not published yet (beta) |
+| Egress | $0.025/GB in NA/EU after the first 1 TB |
+| Amp fee | $0 on non-Enterprise workspaces. Enterprise workspaces pay Amp's self-hosted orb rate |
+
+Example: 120 awake hours a month at 20% CPU costs about $27.50 a month in total on the default size, or $17.55 with `--vcpu 2`. Amp-hosted a1.small (2 vCPU, 4 GiB) is $20.40 and a1.medium (4 vCPU, 8 GiB) is $39.60 for the same hours. On an Enterprise workspace cf-orbs costs more than Amp-hosted orbs: the reason to use it there is that your code stays in your account, not price.
+
+## Commands
+
+| 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 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) |
+| `cf-orbs doctor` | PASS/FAIL per check, each with a one-line fix. Never starts anything |
+| `cf-orbs deploy` | Regenerate `.cf-orbs/wrangler.jsonc` from the config and deploy |
+| `cf-orbs snapshots list` | Project snapshot mappings: Amp snapshot id → Cloudflare snapshot |
+| `cf-orbs snapshots forget <id>` / `forget --all-project` | Drop mappings. The next thread on that project runs setup again |
+| `cf-orbs snapshots prune [--older-than 7d] [--all] [--yes]` | List snapshot data that no orb and no project mapping uses, unused for 7 days. `--yes` deletes it. `--all` removes only the age limit |
+| `cf-orbs upgrade --digest sha256:…` | Move the orb image to a new Amp orb image digest. Keeps the old image key |
+| `cf-orbs uninstall [--yes]` | List (dry run) or delete the Worker, container apps and images |
+
+Every command takes `--json`, `--dir <project>` and `--non-interactive`. Orb ids are `amp-<thread id>`; `cf-orbs status` lists the awake ones.
+
+## Configuration
+
+`cf-orbs.config.jsonc` in your project directory. Edit it, then run `cf-orbs deploy`. Do not edit `.cf-orbs/wrangler.jsonc`: deploy writes it again.
+
+| 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}` |
+| `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) |
+| `warmMinutes` | 10 | After an Amp pause, keep the orb running this many minutes (0-120). The disk is saved first. A message in that time wakes it in under 1 s. Billed like an awake orb (default size ≈ $0.11/h, ≤ $0.02 per pause). 0 = stop at once |
+| `hugePages` | `true` | Each spawn sets transparent huge pages to `always` in the orb (the guest kernel default is `never`). New memory is 3-4x faster to allocate; the work bench 512 MB write went from 1.33 to 0.91 s. `false` leaves the kernel default |
+| `prewarm` | 2 | After each deploy, start N throwaway instances (0-5) from the new image, wait until they answer, destroy them. This raises the odds that the next spawn finds the 1.8 GB image on its host (6 s, not 40-50 s). Cloudflare picks the host, so it is no guarantee. Cost: about 1 min of the orb size per instance. 0 = off |
+| `fastTmpfsGb` | 0 (off) | Each spawn mounts a memory-backed tmpfs of N GiB (`huge=always`) at `/mnt/fast`, for caches and temp data. 512 MB writes in 0.06-0.21 s there, 1.3 s on the root disk. Not in snapshots: lost on pause. Uses memory only for the files in it. 0-8, and at most the orb memory in GiB minus 3 |
+| `projectSnapshotRefresh` | `"off"` | `"on-change"`: when a new thread starts from a project snapshot, cf-orbs forgets the snapshot if amp updated itself or the orb image digest changed (at most once per project per 24 h). The next new thread runs setup. If Amp keeps its cached copy, delete it in Amp → Orb Settings → Snapshots |
+| `providerHost` | `cloudflare` | Where `amp orb provider` runs: in your Worker, or `external` (your own host; see [provider/README.md](https://github.com/meirdick/cf-orbs/blob/main/provider/README.md)) |
+| `images` | `{}` | Extra `ORB_IMAGE` refs → image keys. Each key needs `image/<key>.Dockerfile` |
+| `debugExec` | `false` | Turns on the exec and bench routes. Only for the substrate benchmark |
+| `debugSsh` | `false` | Turns on `wrangler containers ssh` for orbs |
+
+To add toolchains to every orb, edit `image/Dockerfile` (see [image/README.md](https://github.com/meirdick/cf-orbs/blob/main/image/README.md)). Repo setup for one project belongs in that repo's `.agents/setup`.
+
+After `cf-orbs deploy`, an orb that is awake keeps the old Worker code until it pauses (a Cloudflare behaviour). Config changes reach it at the same time.
+
+`cf-orbs deploy` then starts `prewarm` throwaway instances in the background (`prewarm: started 2 instances in the background`); `cf-orbs status` shows how fast they were ready.
+
+## Troubleshooting
+
+Run `cf-orbs doctor` first.
+
+| You see | Do this |
+| --- | --- |
+| `Docker is not running` | Start Docker, check `docker info`, run the command again |
+| `wrangler is not logged in` | `npx wrangler login`, run again |
+| `this login has N Cloudflare accounts` | Add `--account-id <id>` or set `CLOUDFLARE_ACCOUNT_ID` |
+| `Containers need the Workers Paid plan` | Upgrade the account, run the same command again |
+| `this account has no workers.dev subdomain yet` | Run `init` in a terminal (it asks), or add `--subdomain <name>` |
+| `registry push timed out` or `image preparation returned 401`, with `retry n of 3` | Nothing. `init` and `deploy` retry by themselves |
+| `image push to registry.cloudflare.com kept failing (timeout or 401)` | Run `cf-orbs deploy` again. The registry keeps the layers that it already has |
+| Amp's setup log shows `Repository configuration failed` | Amp reuses a cached project snapshot for 72 h, also a bad one. Delete it in Amp → Orb Settings → Snapshots (or `amp projects snapshots delete <owner/repo> --resource <size>`), then `cf-orbs snapshots forget --all-project`. Do the same after any change to `image/Dockerfile` or `.agents/setup` |
+| `Amp rejected the provider token` | Make a new token in Amp Settings → Orbs, then `cf-orbs init --token-file <file>` |
+| `another amp orb provider already uses this token` | Two providers on one token: the second one waits and takes no jobs. Stop the other one (or use a separate token), then run `init` again |
+| `no Amp provider token (the Worker has none after external mode)` | Set `AMP_ORB_PROVIDER_TOKEN` or add `--token-file` |
+| `provider did not report running` | `cf-orbs logs --provider`. A cron restarts the provider every 5 min |
+| An orb does not start | `cf-orbs logs <orb>` shows its redacted bootstrap log; `cf-orbs status <orb>` shows its state and last spawns |
+| `<n>/<max> orbs already running` | Raise `maxRunning`, or let idle threads pause |
+
+Worker logs: `npx wrangler tail --config .cf-orbs/wrangler.jsonc`.
+
+## Security
+
+What leaves your network, and what stays:
+
+- The provider connects out to Amp (`ampcode.com`) for jobs. Nothing connects in.
+- Each orb connects out to `ampcode.com` (tools) and `tunnel.ampcode.com` (portals, Terminal).
+- Amp runs the agent and the model on its own servers. What the agent reads in an orb (code, command output) goes to Amp and its model providers, as with Amp-hosted orbs.
+- The repo checkout, build output and orb disks stay in your Cloudflare account.
+
+Tokens:
+
+- **Amp provider token.** A Worker secret, passed only to the provider container. In external mode it stays on your host. Never in an orb, never logged.
+- **Control token.** `.cf-orbs/control-token` (mode 600, gitignored) and the Worker secret `CONTROL_TOKEN`. It is the bearer for the public API at `https://<worker>.<subdomain>.workers.dev/v1`. Whoever has it can start, pause and delete orbs and read their redacted logs. Keep it like a password.
+- **ORB_TOKEN.** Amp makes a new one for each spawn. cf-orbs passes it to `amp orb bootstrap` in memory and never writes it to disk.
+- Logs and API responses go through redaction (`aop_live_…`, tokens, JWTs, long base64 strings).
+
+Other notes:
+
+- **Egress is open.** An orb can reach any host on the internet, the same as a laptop. There is no allowlist mode in v1.
+- Keep `debugExec` off. When it is on, the control token can run any command in any orb.
+- The container API cannot delete snapshots. Cloudflare keeps snapshot data for up to 30 days after the last restore, also after `cf-orbs uninstall`, unless `cf-orbs snapshots prune --yes` deletes it.
+- The orb user has passwordless sudo (Amp's image needs it).
+
+To report a vulnerability, see [SECURITY.md](https://github.com/meirdick/cf-orbs/blob/main/SECURITY.md).
+
+## 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.
+
+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).
+- 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).
+- Seen once: an orb's Durable Object reset during a long spawn wait. The op failed and Amp retried.
+- Limits: 4 vCPU, 12 GiB memory and 20 GB disk per orb at most (Amp-hosted orbs have 60 GB). One size per install.
+- Writes of new data are slower on the root disk; use `/mnt/fast` for caches (set `fastTmpfsGb`). See [docs/benchmarks.md](https://github.com/meirdick/cf-orbs/blob/main/docs/benchmarks.md#known-limits-measured).
+
+Both platforms are young: Amp self-hosted orbs shipped on Oct 22, 2026, and Container snapshots are in beta. Expect changes.
+
+## Benchmarks
+
+Method, results and costs: [docs/benchmarks.md](https://github.com/meirdick/cf-orbs/blob/main/docs/benchmarks.md). The substrate bench (cold start, restore, pause, parallel restores) runs from a clone of this repo and needs no Amp thread. Steps are in that file.
+
+## Docs
+
+| Doc | Covers |
+| --- | --- |
+| [AGENTS.md](https://github.com/meirdick/cf-orbs/blob/main/AGENTS.md) | Install guide for an AI agent at a terminal |
+| [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 |
+| [Architecture](https://github.com/meirdick/cf-orbs/blob/main/docs/architecture.md) | Parts, control flow, spawn and pause, billing |
+| [Benchmarks](https://github.com/meirdick/cf-orbs/blob/main/docs/benchmarks.md) | Method, results, costs, how to run the substrate bench |
+| [Amp orb provider contract](https://github.com/meirdick/cf-orbs/blob/main/docs/01-amp-orb-provider-contract.md) | The Amp side: dispatch contract, images, pause, project snapshots |
+| [CONTRIBUTING.md](https://github.com/meirdick/cf-orbs/blob/main/CONTRIBUTING.md) | Dev setup and tests |
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/meirdick/cf-orbs/blob/main/LICENSE) and [NOTICE](https://github.com/meirdick/cf-orbs/blob/main/NOTICE). The Amp CLI (`@ampcode/cli`) is proprietary: the provider image installs it from npm; this repo does not include it.

package/bin/cf-orbs.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { main } from "../dist/index.js";
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (e) => {
+    process.stderr.write(
+      `Failed: ${e?.message ?? e} — fix: rerun with CF_ORBS_DEBUG=1 and report the output\n`,
+    );
+    process.exitCode = 1;
+  },
+);

package/dist/api.js

@@ -0,0 +1,124 @@
+// Client for the control plane's public /v1 routes (bearer CONTROL_TOKEN).
+// Routes used (the Worker must serve these when CONTROL_TOKEN is set):
+//   GET  /v1/health                 → 200 {ok:true,...}
+//   GET  /v1/status                 → {registry: RegistrySummary, provider: ProviderStatus}; read loosely
+//   GET  /v1/orbs/:id               → OrbStatus (worker/src/core/types.ts)
+//   GET  /v1/orbs/:id/logs?lines=N  → {containerRunning, log: string}
+//   POST /v1/provider/start         → start ProviderHost now (init only; doctor never calls it). Optional:
+//                                     on 404 init waits for the 5-min cron instead.
+//   POST /v1/provider/restart?ifImageChanged=1 → restart the provider if its image changed (deploy, upgrade);
+//                                     {action, reason, restarted, ...ProviderStatus}
+//   GET    /v1/project-snapshots       → {projectSnapshots: ProjectSnapshotRow[], summary: RegistrySummary}
+//   DELETE /v1/project-snapshots/:id   → {snapshotId, forgotten: boolean}
+//   GET    /v1/snapshots?candidates=1&olderThan=<s> → PruneResult (worker/src/core/registry-core.ts)
+//   POST   /v1/snapshots/forget-many {ids}          → {forgotten: string[], mapped: string[]}
+//   POST   /v1/warm                    → start prewarm (deploy, init); {count, started, orbIds}
+//   GET    /v1/warm                    → {prewarm: config value, last: WarmRunView | null}
+import { CliError } from "./errors.js";
+export const ORB_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+export function makeApi(url, token, f = fetch, timeoutMs = 20_000) {
+    const base = url.replace(/\/+$/, "");
+    const call = async (method, path, body) => {
+        const headers = { accept: "application/json" };
+        if (token)
+            headers.authorization = `Bearer ${token}`;
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        let res;
+        try {
+            res = await f(`${base}${path}`, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (e) {
+            throw new CliError(`cannot reach ${base} (${e.message})`, "check your network, then run cf-orbs doctor");
+        }
+        const text = await res.text();
+        let parsed = text;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch { }
+        return { status: res.status, body: parsed, text };
+    };
+    return {
+        url: base,
+        get: (p) => call("GET", p),
+        post: (p, b) => call("POST", p, b),
+        del: (p) => call("DELETE", p),
+    };
+}
+/** Throw a one-line error for a non-2xx response. */
+export function expectOk(r, what) {
+    if (r.status >= 200 && r.status < 300)
+        return r.body;
+    if (r.status === 401) {
+        throw new CliError(`${what}: control token rejected (401)`, "run cf-orbs deploy to re-send the token in .cf-orbs/control-token");
+    }
+    if (r.status === 404) {
+        throw new CliError(`${what}: route not found (404); the public API is off or the Worker is old`, "run cf-orbs deploy");
+    }
+    const msg = typeof r.body === "object" && r.body && "error" in r.body
+        ? String(r.body.error)
+        : r.text.slice(0, 200);
+    // Worker errors are already "Failed: <cause> — fix: <fix>". Keep its fix; add only what failed.
+    const m = /^Failed: (.*?) — fix: (.*)$/s.exec(msg.trim());
+    if (m)
+        throw new CliError(`${what}: ${m[1]} (HTTP ${r.status})`, m[2]);
+    throw new CliError(`${what}: HTTP ${r.status} ${msg}`, "run cf-orbs doctor");
+}
+export function checkOrbId(id) {
+    if (!ORB_ID_RE.test(id))
+        throw new CliError(`invalid orb id ${JSON.stringify(id)}`, "pass the orb id from cf-orbs status (e.g. amp-T-…)");
+    return id;
+}
+export function providerInfo(status) {
+    if (!status || typeof status !== "object")
+        return { logTail: [] };
+    const p = status.provider;
+    if (!p || typeof p !== "object")
+        return { logTail: [] };
+    const o = p;
+    const arr = [o.logTail, o.log, o.lines].find(Array.isArray);
+    const logTail = (arr ?? []).map(String);
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    return {
+        running: typeof o.running === "boolean" ? o.running : undefined,
+        lastLogLine: str(o.lastLogLine) ?? logTail[logTail.length - 1],
+        logTail,
+        startedAt: str(o.startedAt),
+        restarts: typeof o.restarts === "number" ? o.restarts : undefined,
+        lastError: str(o.lastError) ?? str(o.error),
+        stopped: typeof o.stopped === "boolean" ? o.stopped : undefined,
+        image: str(o.image),
+        build: str(o.build),
+        deployedImage: str(o.deployedImage),
+        deployedBuild: str(o.deployedBuild),
+    };
+}
+/**
+ * Every distinct image key named anywhere in a JSON value: "imageKey" string fields (handles, mappings) and
+ * "imageKeys" string arrays (a Registry summary of keys that live snapshots use).
+ */
+export function collectImageKeys(v, out = new Set()) {
+    if (Array.isArray(v))
+        for (const x of v)
+            collectImageKeys(x, out);
+    else if (v && typeof v === "object") {
+        for (const [k, x] of Object.entries(v)) {
+            if (k === "imageKey" && typeof x === "string")
+                out.add(x);
+            else if (k === "imageKeys" && Array.isArray(x)) {
+                for (const y of x)
+                    if (typeof y === "string")
+                        out.add(y);
+            }
+            else
+                collectImageKeys(x, out);
+        }
+    }
+    return out;
+}