Quickstart

You end with cf-orbs running in your Cloudflare account and a first Amp thread on one of your orbs. Plan on 5 to 15 minutes. One measured install took 4 min 41 s, and most of that was the push of the 1.8 GB orb image.

No Docker on your machine? Use Install with Workers Builds instead.

Before you start

You need	How to check
Node 22 or later	`node --version`
Docker, running	`docker info`
A Cloudflare account on Workers Paid	Dashboard → Workers & Pages → Plans
wrangler logged in to that account	`npx wrangler login`, then `npx wrangler whoami`
The Amp CLI, installed	`amp --version`
An Amp provider token (`aop_live_...`) and its provider name	Amp → Settings → Orbs → Add Provider

The provider is the process that takes orb jobs from Amp. The provider name is the name you type in Amp when you add it. Write it down. Pass the same name to init with --provider-name, because a name that differs from the one in Amp doesn’t work.

The default is cloudflare: if you type cloudflare in Amp, you don’t need the flag. A name saved by an earlier init wins over the default, and init warns you when it uses the default.

You need the Amp CLI only for the first-orb command below. init itself doesn’t run it.

Install

Make a project directory
```
mkdir my-orbs && cd my-orbs
```
Run init
```
npx cf-orbs init --provider-name <name from Amp>
```
init asks for the Amp provider token. It doesn’t show what you type, and the token doesn’t end up in your shell history. No provider in Amp yet? Add it first in Amp → Settings → Orbs → Add Provider. The prompt names this page too.
If npx asks Ok to proceed?, answer yes, or use npx --yes cf-orbs.
In a terminal, init can ask two more questions:
- Cloudflare account. It asks only if wrangler whoami lists more than one account. Type the number of the account, or pass --account-id <id> to skip the question. You’ll find the account ID in npx wrangler whoami, and in the Cloudflare dashboard URL after dash.cloudflare.com/.
- workers.dev subdomain. It asks only if the account has none. Type a short lowercase name, or press Enter to take the suggestion. The Worker URL becomes https://<worker>.<subdomain>.workers.dev. You can also pass --subdomain <name>.
Without a terminal, init doesn’t ask. It stops with a Failed: line that names the flag to add.
Wait for init to finish
init builds and pushes the images, deploys the Worker and starts the provider. The Worker is the cf-orbs control plane, the service that starts, pauses and deletes orbs (see How it works). You may see lines such as deploy: registry push timed out; retry 1 of 3. They’re normal, and init retries by itself.
When it succeeds, the last line is a command to try.

What init does, in order:

Checks Node, Docker, the wrangler login and the account.
Checks that Containers are available on the account.
Writes cf-orbs.config.jsonc, image/Dockerfile and .cf-orbs/.
Registers a workers.dev subdomain if the account has none.
Runs wrangler deploy, which builds and pushes the orb image and the provider image, then deploys the Worker.
Checks /v1/health and /v1/status.
Runs the orb self-test. The Worker starts throwaway instances from the new image (this is called prewarm), and init waits up to 3 min for one to start. Prewarm also raises the chance that a later spawn (an orb start) finds the image already on its host.
Starts the provider and waits until it has run for 15 s with a clean log.

init is safe to run again. It keeps the control token (the secret the CLI uses to call your Worker), and it keeps the Amp token unless you give a new one.

Run a first orb

This command uses your Amp credits. You can run it from any directory:

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

In the Amp app, pick the provider from the provider list when you start a thread. It’s the one you added in Amp → Settings → Orbs.

How to know it worked

amp -ox runs the prompt in a new thread and prints the agent’s answer in your terminal. A slow first run is normal.
The thread shows up in the Amp app, and its setup log shows the orb starting on your provider.
npx cf-orbs status, run from the project directory, lists the orb under awake orbs. Orb ids are amp-<thread id>.
npx cf-orbs logs <orb id> shows the orb’s bootstrap log. The bootstrap is the Amp start-up step that connects the orb to Amp.

If the command hangs or fails, see Troubleshooting.

The first spawn on a new Cloudflare host starts from the image, which takes about 45 s. Then Amp sets up the repo.

Verify

Run both commands from the project directory:

npx cf-orbs doctor
npx cf-orbs status

doctor shows PASS on every line and ends with All checks passed. INFO, SKIP and WARN lines don’t fail the run.
status shows provider: running.

If a line fails, it holds its own fix. See also Troubleshooting.

Choose a smaller orb

The default orb is 4 vCPU, 12 GiB memory and 20 GB disk. For a cheaper orb, run init again with --vcpu 2, which gives 2 vCPU, 6 GiB and 20 GB:

npx cf-orbs init --vcpu 2

init writes the new instance to the config and deploys again. See Change the orb size.