Provider and dispatch

The provider and the dispatch program are how Amp’s orb jobs reach your Cloudflare account.

Provider

The provider is the process amp orb provider. It takes orb jobs from Amp over an outbound connection, so nothing connects in to it. It needs one Amp provider token (aop_live_...).

Run exactly one provider for each token. A second provider on the same token waits and takes no jobs.

One provider serves one orb size, because Amp sends no size in a job. For a second size, make a second provider token and a second install with a different name.

Where the provider runs

Set providerHost in cf-orbs.config.jsonc.

	`cloudflare` (default)	`external`
Where it runs	A small container (`lite`) in your Worker	A machine that you run
Where the Amp token lives	Worker secret `AMP_ORB_PROVIDER_TOKEN`	An env file on your host. Never on Cloudflare
How dispatch reaches the Worker	`http://control.internal`	`https://<worker>.<subdomain>.workers.dev/v1` with the control token
Restart after a failure	Entry loop, a Durable Object alarm every 5 min, and a cron every 5 min	Your service manager, for example systemd

The Worker runs the provider only while the secret AMP_ORB_PROVIDER_TOKEN exists. In external mode, every deploy deletes that secret.

For the external setup, see Run the provider on your own host.

Dispatch

dispatch.sh is the program that amp orb provider runs once for each job. It passes the job to the cf-orbs control plane, which is the Worker (see How it works). It’s POSIX sh and needs only curl, sed, awk, date and sleep.

For each job it:

Prints cf-orbs: <op> <orbId>.
Sends the job to the Worker: POST /v1/orbs/<id>/ops. Then it prints started <op> <opId>, or attaching to running <op> <opId> when the same op is already running.
Long-polls GET /v1/ops/<opId> and prints each progress line from the Worker once.
On success, prints cf-orbs: <op> <orbId> done in <n> s and exits 0. On failure, prints Failed: <cause> — fix: <command> and exits 1.

When a request to the Worker fails and is retried, it also prints control plane: <cause>, retry <n> of 2.

Exit codes: 0 is success, 1 is a failure, 2 is bad input.

The default deadline is 270 s. Amp’s job limit is 300 s. A deadline failure reads Failed: control plane did not finish <op> within 270 s — fix: cf-orbs logs <orbId>.

Curl errors and HTTP 408, 429 and 5xx responses are retried. A request gets 3 attempts in total, 2 s apart.

Secrets in dispatch

No secret is in argv. curl reads the URL, header and body from a config on stdin.
Every printed line is redacted: the exact ORB_TOKEN and control token, aop_live_*, long orb_* tokens, JWT-shaped strings, and Bearer <value>.
The script never prints its environment.

You don’t run dispatch.sh yourself, except in external mode. For its variables, see Environment and files.

Amp shows these lines in the thread setup log, so that is the first place to look when an orb doesn’t start. For the orb’s own bootstrap log, run cf-orbs logs <orb>.