---
title: "Install with Workers Builds"
description: "Install cf-orbs without Docker. Workers Builds builds the images in your Cloudflare account from a git repo."
---

> Documentation Index
> Fetch the complete documentation index at: https://cf-orbs-site.mdick85.workers.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://developers.cloudflare.com/workers/ci-cd/builds/) then builds the two images in your Cloudflare account and deploys the Worker on each push.

> **Preview**
>
> This install path is a preview, and the default install (`cf-orbs init`, local Docker) does not change.

## 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

1. **Make the project**

   ```sh
   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`.
2. **Push the repo**

   Make an empty repo on GitHub or GitLab, then run:

   ```sh
   git remote add origin <repo URL>
   git push -u origin main
   ```

   The repo can be private, and it holds no secrets.
3. **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.
4. **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.
5. **Check**

   ```sh
   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):

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

## What init --no-deploy does

1. 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.
2. Writes `cf-orbs.config.jsonc`, `image/Dockerfile`, `.cf-orbs/`, and the control token.
3. Registers a workers.dev subdomain if the account has none.
4. 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`.
5. 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.
6. 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.
7. Writes `.cf-orbs/state.json` with the Worker URL and `"mode": "git"`.
8. Skips the orb self-test, because the build runs later. A rerun after a build shows the last prewarm result.
9. 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:

```sh
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:

  ```sh
  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](/docs/guides/uninstall/). If you don't disconnect it, the next push deploys the Worker again.

Source: https://cf-orbs-site.mdick85.workers.dev/docs/guides/install-workers-builds/index.mdx