---
title: "Run the provider on your own host"
description: "Keep the Amp provider token off Cloudflare by running amp orb provider yourself."
---

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

# 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

1. **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.
2. **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.
3. **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`:

   ```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).
4. **Write the env file**

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

   ```sh
   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
   ```
5. **Add a service**

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

   ```ini
   [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:

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

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

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