---
title: "Configuration"
description: "The settings of the Worker, their defaults and valid ranges, and the settings file that changes them."
---

> Documentation Index
> Fetch the complete documentation index at: https://cf-opencode.system3inference.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

The Worker reads its settings from the variable `CF_OPENCODE_CONFIG`, a JSON object. A missing key takes its default. You do not edit that variable. You write a settings file, and the CLI applies it.

## Change a setting

1. Write the keys you want to change in `~/.cf-opencode/config.json`, as one JSON object.
2. Run `cf-opencode upgrade`.

```json
{
  "model": "cloudflare-workers-ai/@cf/zai-org/glm-5.3",
  "idlePauseMinutes": 30,
  "instance": { "memoryMib": 8192 }
}
```

`init` and `upgrade` print the keys they read from the file. A key in the file replaces the default. `instance` merges key by key, so the example keeps the default `vcpu` and `diskMb`. Delete the file and run `upgrade` to go back to the defaults.

The CLI stops before the deploy when the file is not one JSON object. A value out of range passes the deploy; the Worker then returns a `Failed:` line that names the key. Correct the file, then run `cf-opencode upgrade` again.

## The Worker hostname

The hostname is not a key in the settings file. Set it with a flag:

```sh
cf-opencode upgrade --domain code.example.com
```

`init` and `upgrade` write it into the copied `wrangler.jsonc` as a Custom Domain route, and keep workers.dev on:

```jsonc
"workers_dev": true,
"routes": [{ "pattern": "code.example.com", "custom_domain": true }],
```

`~/.cf-opencode/install.json` saves the hostname as `domain`, and the URL as `https://<hostname>`. Each later `upgrade` deploys the hostname again. See [Use your own hostname](https://cf-opencode.system3inference.dev/docs/reference/cli/#use-your-own-hostname).

## Keys

| Key | Default | Valid values | Meaning |
| --- | --- | --- | --- |
| `instance` | 2 vCPU, 6144 MiB memory, 20000 MB disk | `lite`, `standard-1` to `standard-4`, or `{ "vcpu", "memoryMib", "diskMb" }` with `vcpu` 1 to 4 | The container size. One size for the whole install. |
| `maxRunning` | `10` | Integer, 1 to 100 | The most workspaces that run at once. |
| `maxAwakeHours` | `12` | Integer, 1 to 168 | A workspace that is awake this long pauses, even while it works, and also while a long job (`cf-opencode-job`) runs. |
| `idlePauseMinutes` | `20` | Integer, 1 to 1440 | Idle time before the Worker pauses a workspace. A running long job is not idle time. |
| `warmMinutes` | `10` | Integer, 0 to 1440 | After an idle pause, the container keeps running this long. `0` stops it at once. |
| `snapshotRefreshDays` | `3` | Integer, 0 to 29 | Days before expiry when the Worker refreshes a paused snapshot. `0` lets unused workspaces expire. |
| `inactivityTimeoutMinutes` | `15` | Integer, 1 to 1440 | The platform inactivity timeout of the container. |
| `alarmSeconds` | `60` | Integer, 10 to 3600 | The interval of the keep-alive alarm. It must be less than `inactivityTimeoutMinutes` in seconds. |
| `serverPort` | `4096` | Integer, 1 to 65535 | The port of `opencode serve` in the container. |
| `checkpointMinutes` | `0` | Integer, 0 to 1440 | When above 0, the Worker saves a snapshot without stopping, once per window of work this long. `0` turns it off. |
| `projectSnapshotRefresh` | `"off"` | `"off"` or `"on-change"` | `"on-change"` lets the Worker mark an out-of-date project snapshot stale and stop using it. It does this at most once per project in 24 hours. `"off"` never does. |
| `lockdown` | `false` | `true` or `false` | `true` turns general internet off. See [Security and trust](https://cf-opencode.system3inference.dev/docs/concepts/security/). |
| `ai` | `true` | `true` or `false` | Route models through the AI binding. See [Models](https://cf-opencode.system3inference.dev/docs/concepts/models/). |
| `aiGateway` | `"default"` | A gateway name: lowercase letters, digits, `_` and `-`, up to 64 characters | The AI Gateway for model requests. |
| `searchProvider` | `"exa"` | A provider name of 1 to 32 characters: lowercase letters, digits, `.`, `_` and `-`, starting with a letter or digit | The Web Search API provider for `cf-opencode-search`. Known providers are `exa`, `linkup` and `ceramic`. |
| `model` | `"cloudflare-workers-ai/@cf/zai-org/glm-5.3"` | `provider/model`, or `""` | The default OpenCode model. An empty value lets OpenCode choose. |
| `a2a` | `false` | `true` or `false` | `true` serves the A2A Agent Card and the JSON-RPC endpoint `/a2a`. See [Hand off tasks over A2A](https://cf-opencode.system3inference.dev/docs/guides/a2a/). |
| `autoReply` | `true` | `true` or `false` | `true` sends one message to a handed-off session that ends its turn with commits that are not pushed or processes left running. See [The automatic reply](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#the-automatic-reply). |
| `store` | `false` | `true` or `false` | `true` adds an R2 bucket, `<worker>-store`, as a file store of the install. `init` and `upgrade` make the bucket and bind it. See [Share files through the store](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#through-the-store). |
| `images` | `{}` | An object of image references | Extra image references mapped to image keys. For advanced use. |

The notify URL is not a setting. A webhook URL often holds its own secret, and these settings are a plain Worker variable. It is the Worker secret `NOTIFY_URL`; set it with `cf-opencode notify-url`. A `notifyUrl` key in the settings file stops `init` and `upgrade` before the deploy with `Failed: notifyUrl in <path> is no longer a setting; the URL is a Worker secret now — fix: remove notifyUrl from the file, then run cf-opencode notify-url`.

An unknown key in the file is not checked. Check the spelling.

The file `worker/wrangler.jsonc` ships with these values: the default `instance`, `maxRunning` 10, `maxAwakeHours` 12, `warmMinutes` 10, `inactivityTimeoutMinutes` 15, `alarmSeconds` 60, `serverPort` 4096, `idlePauseMinutes` 20 and `projectSnapshotRefresh` `"off"`.

## Example

```json
{
  "instance": { "vcpu": 2, "memoryMib": 6144, "diskMb": 20000 },
  "idlePauseMinutes": 30,
  "maxRunning": 5,
  "model": "cloudflare-workers-ai/@cf/zai-org/glm-5.3"
}
```

## Secrets that commands set

Two commands store a value as a Worker secret, not as a setting. A secret does not need `upgrade`, and a running workspace uses a new value at once or on its next `connect`.

| Command | Secret | Meaning |
| --- | --- | --- |
| `cf-opencode git-token` | `GITHUB_TOKEN` | The GitHub token. Workspaces use it for private clones, `git push` and `gh`. `init` also sets it. See [GitHub and private repositories](https://cf-opencode.system3inference.dev/docs/guides/github/). |
| `cf-opencode notify-url` | `NOTIFY_URL` | Where the Worker sends task results and notes. See [Hand off a task](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#get-a-message-when-a-task-ends). |

Both commands read the value from stdin, or ask for it without echo. Neither takes the value as an argument. `--remove` deletes the secret.

## Worker secrets and bindings

These are not part of `CF_OPENCODE_CONFIG`.

| Name | Type | Set by |
| --- | --- | --- |
| `CONTROL_TOKEN` | Secret | `init` |
| `GITHUB_TOKEN` | Secret | `init` or `cf-opencode git-token` |
| `NOTIFY_URL` | Secret | `cf-opencode notify-url`, optional |
| `ANTHROPIC_API_KEY` | Secret | You, optional |
| `OPENAI_API_KEY` | Secret | You, optional |
| `AI` | Binding, Workers AI | `wrangler.jsonc` |
| `BROWSER` | Binding, Browser Run | `wrangler.jsonc` |
| `STORE` | Binding, R2 bucket `<worker>-store` | `init` and `upgrade`, when `store` is `true` |
| `WORKSPACE` | Durable Object, class `WorkspaceSession` | `wrangler.jsonc` |
| `REGISTRY` | Durable Object, class `Registry` | `wrangler.jsonc` |

Source: https://cf-opencode.system3inference.dev/docs/reference/configuration/index.mdx
