---
title: "Config reference"
description: "Every key in cf-orbs.config.jsonc, with its type, default, range, and an example."
---

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

# 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](/docs/guides/configure/).

The key `$schema` is also accepted, and ignored.

## Summary

| Key | Type | Default |
| --- | --- | --- |
| [`name`](#name) | string | `"cf-orbs"` |
| [`instance`](#instance) | object or string | `{ "vcpu": 4, "memoryMib": 12288, "diskMb": 20000 }` |
| [`maxRunning`](#maxrunning) | integer | `20` |
| [`maxAwakeHours`](#maxawakehours) | number | `12` |
| [`checkpointMinutes`](#checkpointminutes) | integer | `0` |
| [`warmMinutes`](#warmminutes) | integer | `10` |
| [`hugePages`](#hugepages) | boolean | `true` |
| [`fastTmpfsGb`](#fasttmpfsgb) | integer | `0` |
| [`prewarm`](#prewarm) | integer | `2` |
| [`projectSnapshotRefresh`](#projectsnapshotrefresh) | string | `"off"` |
| [`providerHost`](#providerhost) | string | `"cloudflare"` |
| [`providerInstance`](#providerinstance) | string | `"lite"` |
| [`images`](#images) | object | `{}` |
| [`debugSsh`](#debugssh) | boolean | `false` |
| [`debugExec`](#debugexec) | boolean | `false` |
| [`inactivityTimeoutMinutes`](#inactivitytimeoutminutes) | integer | `15` |
| [`alarmSeconds`](#alarmseconds) | integer | `60` |
| [`ampImageDigest`](#ampimagedigest) | string | The pinned Amp digest |

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

```jsonc
"name": "cf-orbs-small"
```

## instance

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

Custom form:

| Field | Range |
| --- | --- |
| `vcpu` | A number from 1 to 4. Fractions such as `1.5` are allowed |
| `memoryMib` | An integer, at most 12288, and at least 3072 for each vCPU |
| `diskMb` | An integer from 8000 to 20000 |

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

```jsonc
"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.

```jsonc
"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.

```jsonc
"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.

```jsonc
"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.

```jsonc
"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.

```jsonc
"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`.

```jsonc
"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.

```jsonc
"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](/docs/concepts/orb-lifecycle/#project-snapshot-refresh).

```jsonc
"projectSnapshotRefresh": "on-change"
```

## providerHost

`"cloudflare"` or `"external"`: where `amp orb provider` runs. See [Provider and dispatch](/docs/concepts/provider-and-dispatch/).

```jsonc
"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.

```jsonc
"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.

```jsonc
"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.

```jsonc
"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](/docs/reference/cli/#bench). `cf-orbs doctor` shows `WARN` while it is `true`. This key is not in the example config file.

```jsonc
"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.

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