Skip to content

Configuration

The settings of the Worker, their defaults and valid ranges, and the settings file that changes them.

Updated

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

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.
idlePauseMinutes 20 Integer, 1 to 1440 Idle time before the Worker pauses a workspace.
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.
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
WORKSPACE Durable Object, class WorkspaceSession wrangler.jsonc
REGISTRY Durable Object, class Registry wrangler.jsonc

Type to search…

↑↓ navigate↵ selectEsc close