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
- Write the keys you want to change in
~/.cf-opencode/config.json, as one JSON object. - Run
cf-opencode upgrade.
{
"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:
cf-opencode upgrade --domain code.example.cominit and upgrade write it into the copied wrangler.jsonc as a Custom Domain route, and keep workers.dev on:
"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.
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. |
ai |
true |
true or false |
Route models through the AI binding. See 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. |
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. |
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. |
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
{
"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. |
cf-opencode notify-url |
NOTIFY_URL |
Where the Worker sends task results and notes. See Hand off a task. |
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 |