This page is for a coding agent or a CI job that installs cf-opencode for a user. Everything runs in the user’s Cloudflare account.
Never print a token or pass it as a command argument.
Steps
-
Check the machine. These must succeed: Node 22 or newer,
docker info, anddocker buildx version. -
Get credentials. Use one of these:
- The user ran
npx wrangler loginon this machine. - The user gave an API token with Workers Scripts Write and Workers Containers Write. Put it in
CLOUDFLARE_API_TOKEN, or in a mode-600 file for--token-file.
Ask for one of these if neither exists. Never ask for the token in chat.
- The user ran
-
Install the CLI. From a checkout:
npm ci && npm pack -w cli && npm install -g ./cf-opencode-*.tgzOr use
npx cf-opencode. -
Run init:
cf-opencode init --yes --jsonAdd
--account <id>if the login sees several accounts. You can setCLOUDFLARE_ACCOUNT_IDinstead. -
Verify:
cf-opencode doctorIt must exit 0. Every line is a check mark or a
!. -
Tell the user the Worker URL and the next step:
cf-opencode connectfrom a git checkout.
Output
With --json, progress goes to stderr. stdout is one JSON document. On success it has ok: true, the Worker url, and next. On failure, it has ok: false and an error line.
A failure is one or more Failed: <cause> — fix: <action> lines. Do the fix. Then run the same command again. Reruns are safe and keep the control token.
--yes stops all prompts. --json and a non-terminal stdin imply it.
An existing Worker
If init reports a Worker with the same name that this machine did not deploy, ask the user. Pass --adopt only with their consent. --adopt replaces the control token of that Worker. --name <other> makes a separate install.
GitHub
init gives workspaces the gh login of the machine, if there is one. In CI (CI or GITHUB_ACTIONS set), it does not use a gh login without a terminal.
Pass --no-github if the user did not agree. cf-opencode git-token sets it later.
Models and browsing
Models and browsing use the AI and Browser Run bindings of the account. You need no model key and no browser token.