Run the provider on your own host

External mode runs the provider (the amp orb provider process that takes orb jobs from Amp) on a machine you run, not on Cloudflare. Use it when you want the Amp provider token to stay off Cloudflare, or when the Cloudflare provider doesn’t fit, for example when lite runs out of memory.

You run amp orb provider on a machine that stays on. The orbs still run on Cloudflare.

Switch to external mode

Set the mode
Run npx cf-orbs init --provider external, or set "providerHost": "external" in cf-orbs.config.jsonc and run npx cf-orbs deploy.
In external mode, every deploy deletes the Worker secret AMP_ORB_PROVIDER_TOKEN and sends CONTROL_TOKEN again. Within 5 min the Worker stops its own provider.
Wait before you start the external provider
Don’t start the external provider until the Cloudflare provider has stopped, because a second provider on one token waits and takes no jobs. cf-orbs doctor fails while the Cloudflare provider still runs.

Install on the host

The host needs Node 22 or later and curl. Install the Amp CLI and copy dispatch.sh from .cf-orbs/dispatch/dispatch.sh:

sudo npm install -g @ampcode/cli@<version in provider/Dockerfile>
sudo install -d -m 0755 /opt/cf-orbs
sudo install -m 0755 .cf-orbs/dispatch/dispatch.sh /opt/cf-orbs/dispatch.sh
sudo useradd --system --home /var/lib/cf-orbs --create-home cf-orbs

Use the same @ampcode/cli version as .cf-orbs/provider/Dockerfile (the AMP_CLI_VERSION argument).

Write the env file

Make /etc/cf-orbs/provider.env, mode 0600, owner root:

AMP_ORB_PROVIDER_TOKEN=aop_live_...
CF_ORBS_URL=https://<worker>.<subdomain>.workers.dev
CF_ORBS_CONTROL_TOKEN=<contents of .cf-orbs/control-token>
AMP_SKIP_UPDATE_CHECK=1

Add a service

Make /etc/systemd/system/cf-orbs-provider.service:

[Unit]
Description=cf-orbs Amp orb provider
Wants=network-online.target
After=network-online.target

[Service]
User=cf-orbs
EnvironmentFile=/etc/cf-orbs/provider.env
ExecStart=/usr/bin/env amp orb provider /opt/cf-orbs/dispatch.sh
Restart=always
RestartSec=5
KillSignal=SIGTERM
TimeoutStopSec=30
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/lib/cf-orbs

[Install]
WantedBy=multi-user.target

Then start it:

sudo systemctl daemon-reload
sudo systemctl enable --now cf-orbs-provider
journalctl -u cf-orbs-provider -f

init --provider external prints the env values and a command for a quick manual run. To run it by hand from your project directory:

export AMP_ORB_PROVIDER_TOKEN=aop_live_...
export CF_ORBS_URL=https://<worker>.<subdomain>.workers.dev
export CF_ORBS_CONTROL_TOKEN_FILE=$PWD/.cf-orbs/control-token
amp orb provider .cf-orbs/dispatch/dispatch.sh

You can also run provider/entry.sh as ExecStart, which adds the same redaction and log file as the Cloudflare mode. Set CF_ORBS_DISPATCH=/opt/cf-orbs/dispatch.sh and CF_ORBS_PROVIDER_LOG=/var/lib/cf-orbs/provider.log.

Don’t pass --allow-multiple to amp orb provider.

Check

In external mode, cf-orbs doctor shows SKIP provider with the text providerHost is external; check the amp orb provider service on your host. Check the service on your host with journalctl instead.

Go back to the Cloudflare provider

Stop the external service first, so only one provider uses the token. Then set "providerHost": "cloudflare" in the config and run cf-orbs init --token-file <file> with the Amp provider token.