---
title: "Environment and files"
description: "Environment variables, Worker secrets, and the files in a cf-orbs project."
---

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

# Environment and files

## Environment variables for the CLI

| Variable | Used by | Meaning |
| --- | --- | --- |
| `AMP_ORB_PROVIDER_TOKEN` | `init` | The Amp provider token. A secret. Used when `--token-file` is not given |
| `AMP_ORB_PROVIDER_NAME` | `init` | The Amp provider name. Used when `--provider-name` is not given |
| `CLOUDFLARE_ACCOUNT_ID` | `init` | The Cloudflare account. Used when `--account-id` is not given |
| `CF_ORBS_SUBDOMAIN` | `init` | The workers.dev subdomain to register. Used when `--subdomain` is not given |
| `CF_ORBS_URL` | `status`, `logs`, `doctor`, `snapshots` | The control-plane URL. Used when `--url` is not given. Else the URL in `.cf-orbs/state.json` |
| `CF_ORBS_DEBUG` | All | Set to any value to print a stack trace for unexpected errors |
| `CI` | All | When set, the CLI runs non-interactive |

## Worker secrets

| Secret | Meaning |
| --- | --- |
| `CONTROL_TOKEN` | The bearer for the public `/v1` API. `init` and `deploy` set it from `.cf-orbs/control-token`. If it is not set, every public route returns 404 |
| `AMP_ORB_PROVIDER_TOKEN` | The Amp provider token. Only the provider container gets it. In external mode, `deploy` deletes it |

## Worker variables

`cf-orbs deploy` writes these into `.cf-orbs/wrangler.jsonc`, so you don't set them.

| Variable | Meaning |
| --- | --- |
| `CF_ORBS_CONFIG` | Your config as JSON |
| `CF_ORBS_PROVIDER_BUILD` | A hash of the provider image inputs. The Worker restarts the provider container when it changes |

## Provider and dispatch variables

These matter in external mode, or when you run `provider/entry.sh` yourself. `dispatch.sh` is the program the provider runs for each Amp job.

| Variable | Meaning |
| --- | --- |
| `ORB_OPERATION` | Set by Amp. `spawn`, `pause`, or `delete`. Other values fail with exit 2 |
| `ORB_ID` | Set by Amp. Must match `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` |
| `ORB_SNAPSHOT_ID` | Set by Amp. Sent as the project snapshot id when set |
| `ORB_IMAGE`, `ORB_TOKEN`, `AMP_URL` | Set by Amp. Sent on spawn only |
| `CF_ORBS_URL` | Control-plane base URL for `dispatch.sh`. Default `http://control.internal`. It must be `https://`, except for the hosts `control.internal`, `localhost`, and `127.0.0.1` |
| `CF_ORBS_CONTROL_TOKEN` | The bearer for the public API: the contents of `.cf-orbs/control-token` |
| `CF_ORBS_CONTROL_TOKEN_FILE` | A file with the bearer on its first line. Used when `CF_ORBS_CONTROL_TOKEN` is not set |
| `CF_ORBS_DEADLINE_SECONDS` | Give up after this many seconds (1 to 3600). Default 270 |
| `CF_ORBS_PROVIDER_LOG` | `entry.sh` log file. Default `/var/log/cf-orbs-provider.log` |
| `CF_ORBS_LOG_MAX_BYTES` | `entry.sh` log cap. Default 5 MB |
| `CF_ORBS_AMP_BIN` | The amp binary for `entry.sh`. Default `amp` |
| `CF_ORBS_DISPATCH` | The dispatch program for `entry.sh`. Default `/app/dispatch.sh` |
| `AMP_SKIP_UPDATE_CHECK` | Set to `1` on an external host so amp does not check for updates |

When the URL host is `control.internal`, `dispatch.sh` sends no bearer. Any other host needs the bearer, and without one the script exits 2.

## Project files

| Path | Meaning |
| --- | --- |
| `cf-orbs.config.jsonc` | Your config. Edit it |
| `image/Dockerfile` | The orb image. Edit it. `init` writes it once |
| `image/<key>.Dockerfile` | An extra image key |
| `.cf-orbs/wrangler.jsonc` | Generated. `deploy` overwrites it |
| `.cf-orbs/worker/`, `.cf-orbs/provider/`, `.cf-orbs/dispatch/` | Generated copies of the templates. `deploy` replaces them |
| `.cf-orbs/state.json` | Worker URL, account id, provider name, mode, Worker name, deploy time, CLI version. No tokens |
| `.cf-orbs/control-token` | The control token. Mode 600. Git ignores it. Treat it like a password |
| `.gitignore` | `init` adds `.cf-orbs/*`, `!.cf-orbs/state.json`, `.cf-orbs/control-token`, `.wrangler/`, and `node_modules/`. In a Workers Builds project it keeps out only `.cf-orbs/control-token`, `.cf-orbs/state.json`, `.wrangler/`, and `node_modules/` |
| `package.json`, `package-lock.json` | Workers Builds projects only. They pin the wrangler version |

## Redaction

Every line that the CLI prints redacts `aop_live_` tokens and the secret values it knows. Worker logs, API responses, and the shell scripts also redact JWT-shaped strings and long token-like runs.

Source: https://cf-orbs-site.mdick85.workers.dev/docs/reference/environment/index.mdx