---
title: "Configure cf-orbs"
description: "Change the config file, apply the change, and know when it reaches running orbs."
---

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

# Configure cf-orbs

The only config you edit is `cf-orbs.config.jsonc` in your project directory. `cf-orbs init` writes it, and the format is JSONC: JSON with comments and trailing commas.

> **Caution**
>
> Don't edit `.cf-orbs/wrangler.jsonc`. `cf-orbs deploy` generates it from your config and overwrites it.

## Change a setting

1. **Edit the file**

   Open `cf-orbs.config.jsonc` and change a value. For example:

   ```jsonc
   {
     "maxRunning": 10,
     "warmMinutes": 0
   }
   ```

   Keys you leave out take their defaults. See the [config reference](/docs/reference/config/).
2. **Deploy**

   ```sh
   npx cf-orbs deploy
   ```

   `deploy` checks the file first, and a bad value stops it with one `Failed: ... — fix: ...` line.

In a Workers Builds project, don't run `deploy`. See [Install with Workers Builds](/docs/guides/install-workers-builds/#upgrades).

## What the check rejects

The CLI checks the file before it deploys. The Worker applies the same range rules, so a config that the CLI accepts won't fail in the Worker. Only the CLI rejects unknown keys; the Worker ignores them. The CLI check stops on:

- An unknown key. This catches typos.
- A number outside its range.
- `instance` of `lite`, `basic`, or `dev`. They are too small for the orb image.
- Memory below 3 GiB for each vCPU.
- `checkpointMinutes` between 1 and 14.
- `fastTmpfsGb` larger than the orb memory in GiB minus 3.
- A `name` that is not lowercase letters, digits, and dashes (63 characters at most).

## When a change reaches running orbs

After `cf-orbs deploy`, an orb that is awake keeps the old Worker code until it pauses (that's how Cloudflare works). A config change reaches such an orb at the same time as the code.

## Use a second install

The `name` key sets the Worker name. A second install, for example one with another orb size, needs another `name` and another Amp provider token. Run `cf-orbs init --name <worker>` in a new directory.

## Decide the main settings

| Goal | Setting |
| --- | --- |
| Lower the cost of each hour | `instance` (see [Change the orb size](/docs/guides/change-orb-size/)) |
| Limit the bill from many threads | `maxRunning`, `maxAwakeHours` |
| Wake faster after a pause | `warmMinutes` (default 10) |
| Lose less work when Cloudflare stops a container | `checkpointMinutes` |
| Speed up caches and temp files | `fastTmpfsGb` (mounts `/mnt/fast`) |
| Raise the chance of a host that has the image | `prewarm` |
| Keep new threads from using a stale project snapshot | `projectSnapshotRefresh` |

Commit `cf-orbs.config.jsonc` after a change, because you can't make it again. See [Back up and restore](/docs/guides/back-up-and-restore/).

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