Config reference

The config file is cf-orbs.config.jsonc in the project directory. It is JSONC (JSON with comments). Unknown keys are an error, and a key you leave out takes its default. After a change, run cf-orbs deploy. See Configure cf-orbs.

The key $schema is also accepted, and ignored.

Summary

name

The Worker name. A second install needs another name. Use lowercase letters, digits, and dashes. Start with a letter or digit. Up to 63 characters. cf-orbs init --name <worker> sets it.

"name": "cf-orbs-small"

instance

The orb size. Each install has one size, because Amp sends no size with a job.

Custom form:

The object takes only these three keys. The CLI rejects any other key.

Named form: "standard-1", "standard-2", "standard-3", or "standard-4", with 4096, 6144, 8192, and 12288 MiB of memory. "lite", "basic" and "dev" are rejected because they’re too small for the orb image. Any other name is rejected as unknown.

cf-orbs init --vcpu N writes { "vcpu": N, "memoryMib": N x 3072, "diskMb": 20000 }.

"instance": { "vcpu": 2, "memoryMib": 6144, "diskMb": 20000 }

maxRunning

The cap on awake orbs (1 to 1000). When this many orbs are awake, a new spawn fails with Failed: <n>/<max> orbs already running — fix: raise maxRunning in cf-orbs.config.jsonc or pause idle threads. A warm orb counts as awake.

"maxRunning": 10

maxAwakeHours

The watchdog (a timer in each orb’s Durable Object) pauses an orb that stays awake longer than this many hours. It saves a snapshot and stops the orb. A number from 1 to 720.

"maxAwakeHours": 8

checkpointMinutes

0 turns checkpoints off. Otherwise cf-orbs saves a snapshot of an awake orb every N minutes, if it has changes. The value is 0, or 15 to 1440; a value from 1 to 14 is rejected.

"checkpointMinutes": 30

warmMinutes

After Amp pauses an orb, keep it running for this many minutes (0 to 120). This is the warm pause. The disk is saved first, and a message in that time needs no restore and no restart. Measured: 3.9 s from the message to the first tool result, including the time Amp takes. A warm orb bills like an awake orb. 0 stops the container at once.

"warmMinutes": 0

hugePages

When true, each spawn sets transparent huge pages to always in the orb (the guest kernel ships with never). New memory is then 3 to 4 times faster to allocate, though programs may use a bit more memory. false keeps the kernel default.

"hugePages": false

fastTmpfsGb

0 turns it off. Otherwise each spawn mounts a memory-backed tmpfs (a RAM disk) of N GiB (huge=always) at /mnt/fast, for caches and temp data. Writes there are 4 to 14 times faster than on the root disk. The content isn’t saved in snapshots, so it’s lost on pause. It uses memory only for the files in it.

The value is 0 to 8, and at most the orb memory in GiB minus 3. A larger value fails with fastTmpfsGb <n> leaves less than 3 GiB of the orb's <m> GiB memory.

"fastTmpfsGb": 4

prewarm

After each deploy, upgrade, or init, the Worker starts this many throwaway instances (0 to 5) from the new image, waits until they answer, then destroys them. The first spawn on a host without the image pulls 1.8 GB (40 to 50 s). Prewarm raises the chance that the next spawn lands on a host that already has it. Cloudflare picks the host, so there’s no guarantee. Each instance costs about 1 minute of the orb size. 0 turns it off, and also skips the init self-test.

"prewarm": 0

projectSnapshotRefresh

"off" or "on-change". With "on-change", a spawn from an Amp project snapshot checks whether amp updated itself or the orb image changed since the snapshot. If either did, cf-orbs forgets the mapping (at most once for each project in 24 hours). See Orb lifecycle.

"projectSnapshotRefresh": "on-change"

providerHost

"cloudflare" or "external": where amp orb provider runs. See Provider and dispatch.

"providerHost": "external"

providerInstance

"lite", "standard-1" or "standard-2": the size of the provider container when providerHost is "cloudflare". The container runs all the time. "lite" (1/16 vCPU, 256 MiB) costs about $2 a month and handled 10 spawns at once in tests. "standard-1" (1/2 vCPU, 4 GiB) costs about $27 a month. Raise the size if cf-orbs doctor reports a slow provider. cf-orbs deploy restarts the provider on the new size.

"providerInstance": "standard-1"

images

An object that maps each ORB_IMAGE reference to an image key. A key <key> needs image/<key>.Dockerfile, and must match ^[a-z0-9][a-z0-9_-]{0,62}$. The keys orb and provider are reserved. The default Amp image always maps to the key orb. cf-orbs upgrade adds old images here.

"images": {
  "us-central1-docker.pkg.dev/amp-prod-0/amp-orb/amp-orb@sha256:<old digest>": "orb-0123456789ab"
}

debugSsh

When true, the generated Wrangler config turns on wrangler containers ssh for orbs. Use it only to debug.

"debugSsh": true

debugExec

When true, the Worker turns on the exec and bench routes, and whoever has the control token can then run any command in any orb. Use it only for the substrate benchmark (a test of the container platform alone, with no Amp thread). See the CLI reference. cf-orbs doctor shows WARN while it is true. This key is not in the example config file.

"debugExec": false

inactivityTimeoutMinutes

The inactivity timeout that the Worker sets on each orb container, in minutes (5 to 360). The watchdog extends it at each check. This key isn’t in the example config file, and most installs don’t change it.

alarmSeconds

How often the watchdog alarm checks an awake orb, in seconds (10 to 3600). It must be shorter than inactivityTimeoutMinutes. This key isn’t in the example config file, and most installs don’t change it.

ampImageDigest

The Amp orb image digest that the install pins, in the form sha256:<64 hex>. cf-orbs upgrade sets it, so don’t edit it by hand. If a job names a different digest, cf-orbs uses the pinned orb image and logs a note.