You end with a Worker in your Cloudflare account and a first workspace for one of your repositories. The first deploy builds the workspace image. It takes a few minutes.
Requirements
| You need | How to check |
|---|---|
| Node 22 or newer | node --version |
| Docker, running, with the buildx plugin | docker info and docker buildx version |
| A Cloudflare account on the Workers Paid plan | init checks this. The plan is under Workers & Pages, Plans, in the Cloudflare dashboard |
| OpenCode 2 on this machine | opencode --version |
Docker Desktop includes buildx. On Debian or Ubuntu, run apt install docker-buildx-plugin. Wrangler builds the workspace image on your machine on each deploy.
Install OpenCode 2 with this command:
curl -fsSL https://opencode.ai/v2/install | bashYou need no model key and no Browser Run token. Models and browsing use bindings on your Worker.
Install
Run init from any directory.
npm install -g cf-opencode
cf-opencode initThe package cf-opencode is on npm. It carries the Worker source and the workspace image. You do not need a checkout.
If npm cannot write to its global folder, do not install. Put npx before each command on this page instead, for example npx cf-opencode init.
git clone https://github.com/meirdick/cf-opencode
cd cf-opencode
npm ci && npm pack -w cli
npm install -g ./cf-opencode-*.tgz
cf-opencode initWhat init does
init checks everything before it changes anything. It prints every problem at once, one Failed: … — fix: … line each. See Troubleshooting.
Check the machine and the account
initchecks Node, Docker and buildx, the Cloudflare login, the account and Workers Paid. It also checks if a Worker with the same name exists that this machine did not deploy.On a terminal with no login,
initofferswrangler loginin your browser. If the login sees several accounts, it asks which one to use.Deploy
initbuilds the workspace image and deploys the Workercf-opencode. The log is in~/.cf-opencode/deploy.log.initretries a failed image push twice.Store the control token
initmakes a control token and stores it in~/.cf-opencode/control-tokenand on the Worker. It waits until the Worker accepts the token. A rerun keeps the same token.Set up GitHub
initsets up GitHub once, so private repositories,git pushandghwork in every workspace.- If
ghis logged in on this machine,initoffers to use that login. On a terminal it asks first. With--yesit uses the login without asking. - If
ghis not logged in,initasks you to paste a token. Press Enter to skip. --no-githubskips this step. You can runcf-opencode git-tokenlater.
The token becomes a Worker secret. It never enters a workspace. See GitHub and private repositories.
- If
Install the handoff skill
If Claude Code or OpenCode has a config folder on this machine,
initoffers to install the handoff skill for it. On a terminal it asks first. The skill tells the agent how to hand a task to a workspace. It never replaces a skill file that differs.--no-skillskips this step. See Hand off a task.
At the end, init prints the Worker URL and the next command:
Ready: https://cf-opencode.example.workers.dev
Next, from any git checkout:
cf-opencode connectConnect
Go to a git checkout and run connect:
cd my-project
cf-opencode connectThe workspace ID comes from the directory name: lowercase, with each other character changed to -. The directory My App gives the workspace my-app. The first connect clones the origin remote into the workspace, checks out your branch, and starts OpenCode there. Your local OpenCode opens against the workspace.
A directory with no origin remote gets an empty workspace: nothing is cloned.
If your branch is not pushed, the workspace starts on the default branch and creates your branch from it. Push the branch first to bring your commits.
To give the agent a task and close the laptop, run cf-opencode run "<task>". See Hand off a task.
Later connects restore the snapshot. Installed packages and uncommitted work are still there.
Close the laptop
The agent runs in the workspace. Give it a task and close the laptop. The task continues.
The workspace stays awake while an OpenCode session runs, a terminal prints output, or a request arrives through the Worker. After idlePauseMinutes (default 20) with none of these, the workspace saves its disk and stops. See How it works.
Come back
When you quit OpenCode, it prints a line such as Continue opencode -s ses_…. Do not use that command. It starts a local session. The session lives in the workspace.
Reopen the last session of the workspace:
cf-opencode connect --continueOpen a session by ID:
cf-opencode connect --session ses_abc123To list sessions across all your workspaces, run cf-opencode sessions. It wakes nothing. See Sessions.
Check the install
cf-opencode doctordoctor checks Node, OpenCode, ssh, the control token, the Worker and its bindings. It starts no workspace.