Install with Workers Builds

Use this path if you don’t have Docker on your machine. You push a GitHub or GitLab repo. Workers Builds then builds the two images in your Cloudflare account and deploys the Worker on each push.

Before you start

You need	How to check
Node 22 or later	`node --version`
A GitHub or GitLab account	You make one empty repo
A Cloudflare account on Workers Paid	Dashboard → Workers & Pages → Plans
wrangler logged in to that account	`npx wrangler login`, then `npx wrangler whoami`
git	`git --version`
An Amp provider token and its provider name	You can also set the token later

You do not need Docker.

Steps

Make the project
```
mkdir my-orbs && cd my-orbs
npx cf-orbs init --no-deploy --provider-name <name from Amp> --token-file <file>
```
Put the token in a file with mode 600. Without --token-file and without AMP_ORB_PROVIDER_TOKEN, init asks in a terminal. Press Enter to skip and set the token later.
--provider external does not work with --no-deploy.
Push the repo
Make an empty repo on GitHub or GitLab, then run:
```
git remote add origin <repo URL>
git push -u origin main
```
The repo can be private, and it holds no secrets.

Connect the repo to the Worker

In the Cloudflare dashboard, go to Workers & Pages → your Worker → Settings → Builds → Connect. Use these settings:

Setting	Value
Repository	The repo from step 2
Branch	`main`
Build command	Empty
Deploy command	`npx wrangler deploy --config .cf-orbs/wrangler.jsonc`
Root directory	`/`
Previews (builds for non-production branches)	Off
API token	The default build token
Build watch paths (include)	`image/`, `.cf-orbs/`, `cf-orbs.config.jsonc`, `package*.json`

The Worker name in the dashboard must be the name in cf-orbs.config.jsonc, and init makes them the same. If no build starts, push a commit.

Wait for the first build
Measured on 2026-11-02, the first build took 10 min 35 s. A build can also wait 2 to 4 min in the queue, and builds have a 20 min limit.
Check
```
npx cf-orbs status
npx cf-orbs doctor
```
The Worker starts the provider on its 5-min cron, so status can show the provider as not running for up to 5 min after the first build.

Then run a first thread (this uses Amp credits):

amp -ox "hello from cf-orbs" --orb-provider <name from Amp>

What init –no-deploy does

Checks Node, the wrangler login, and the account, but not Docker. It runs wrangler containers list and stops on a clear plan or login error.
Writes cf-orbs.config.jsonc, image/Dockerfile, .cf-orbs/, and the control token.
Registers a workers.dev subdomain if the account has none.
Writes package.json (wrangler pinned to the CLI’s version), package-lock.json, and .gitignore. The .gitignore keeps out .cf-orbs/control-token and .cf-orbs/state.json.
If the directory is not in a git repo, runs git init -b main and makes a first commit. Before the commit, it looks for an aop_live_ token or the control token in the staged files, and stops if it finds one.
Creates the Worker (a placeholder until the first build) and sets the secrets CONTROL_TOKEN and AMP_ORB_PROVIDER_TOKEN. Secrets stay on the Worker across builds.
Writes .cf-orbs/state.json with the Worker URL and "mode": "git".
Skips the orb self-test, because the build runs later. A rerun after a build shows the last prewarm result.
Prints the next steps and the dashboard settings. With --json, the output has mode: "git" and a settings object.

init --no-deploy is safe to run again. It keeps the control token and makes no second commit.

Set the Amp token later

If you gave no token in step 1:

npx cf-orbs init --no-deploy --token-file <file>

This sets the secret on the Worker, and no build is needed. The cron starts the provider within 5 min.

Upgrades

Every change goes through git: edit, commit, push. Workers Builds then builds and deploys it.

Change	Do
Config (size, `maxRunning`, `warmMinutes`, …)	Edit `cf-orbs.config.jsonc`, then run `npx cf-orbs init --no-deploy` to write `.cf-orbs/wrangler.jsonc` again. Commit both and push
Toolchains in the orb image	Edit `image/Dockerfile`, commit and push
New Amp orb image	Run `npx cf-orbs upgrade --digest sha256:<hex> --no-deploy`, then commit and push
New cf-orbs version	Update the CLI and run `npx cf-orbs init --no-deploy`, then commit and push

A new provider image (from a new cf-orbs version) restarts the provider at the next 5-min check.

Caveats

No Docker layer cache. Each build builds the orb image again, so each push makes a new orb image digest. The first spawn on each Cloudflare host then pulls the 1.8 GB image again (40 to 50 s). The path filters keep docs-only pushes from building.
No prewarm. cf-orbs deploy asks the Worker to prewarm after a deploy (start throwaway instances so a host already has the new image). A Workers Builds deploy does not. To prewarm after a build, send the request yourself. Note that this puts the control token on the curl command line:
```
curl -fsS -X POST -H "Authorization: Bearer $(cat .cf-orbs/control-token)" \
  "$(node -p 'require("./.cf-orbs/state.json").url')/v1/warm"
```
The account ID is in the repo. .cf-orbs/wrangler.jsonc names your account. That isn’t a secret, but keep the repo private if you do not want it seen.
Manual steps. cf-orbs cannot do these for you: install the Cloudflare GitHub or GitLab app, connect the repo, and set the Amp token if you skipped it.
The default build token can deploy any Worker in the account.
Awake orbs keep old Worker code until they pause, as with cf-orbs deploy.

Troubleshooting

You see	Do this
`doctor`: health `route not found (404)` with fix `wait for the Workers Builds build`	The first build has not finished. Look at Workers & Pages → your Worker → Deployments
Build log: `Missing entry-point`	The root directory is not `/`, or `.cf-orbs/` is not in the repo. Check `.gitignore` (`cf-orbs doctor` checks it too)
Build log: `Could not route to /client/v4/accounts/...`	`account_id` in `.cf-orbs/wrangler.jsonc` is another account. Run `init --no-deploy --account-id <id>` again, then commit and push
Build log: `Containers need the Workers Paid plan`	Upgrade the account, then retry the build
Build timed out (20 min)	Retry the build. Measured builds took 6 to 11 min
`doctor`: `wrangler pin` fails	`package.json` pins another wrangler. Set it to the version in the fix line, run `npm install`, then commit and push
`doctor`: `gitignore` or `secrets in git` fails	Do the fix in the line. If a token was pushed, make a new one

To remove the install, disconnect the repo first (Settings → Builds → Disconnect), then see Uninstall. If you don’t disconnect it, the next push deploys the Worker again.