You end with a Worker in your Cloudflare account and a first task that an agent ran in a workspace. A workspace is one Cloudflare Container with a disk. It holds a clone of your repository, and the agents run in it. 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 that Containers are available |
| A licence key | skyworker login stores it |
OpenCode 2 on this machine, for connect only |
opencode --version |
A git checkout with an origin remote, for run |
git remote get-url origin |
To install OpenCode 2: curl -fsSL https://opencode.ai/v2/install | bash. You need it only to open a workspace in OpenCode on this machine. skyworker connect --no-attach and skyworker run work with no OpenCode.
Docker Desktop includes buildx. On Debian or Ubuntu, run apt install docker-buildx-plugin. Wrangler builds the workspace image on your machine at each deploy.
You need no model key. Models and browsing use bindings of your Cloudflare account.
Install
npm install -g skyworkerIf npm cannot write to its global folder, do not install. Put npx before each skyworker command instead, for example npx skyworker init.
Log in
skyworker loginThe command asks for your licence key. It does not show the key on the screen. Never type the key as an argument. The command line is logged. You can also pipe the key in, or set SKYWORKER_LICENSE_KEY.
The first command after the login downloads the build of Skyworker for your key. The package checks the signature of the build before it unpacks it. A build with no valid signature does not run.
Initialise
init needs a Cloudflare login. Use one of these:
- Run
npx wrangler loginon this machine. In a terminal,initoffers to run it for you when you are not logged in. - Set
CLOUDFLARE_API_TOKENto a token with Workers Scripts Write and Workers Containers Write. Or use--token-file <path>.
Then run:
skyworker initinit 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 Containers access. With several accounts it asks which one to use. In a script, pass--account <id>.Deploy
initbuilds the workspace image and deploys the Workerskyworker. The log is in~/.skyworker/deploy.log.Store the control token
initmakes a control token: the secret of your install. The CLI sends it with each request to your Worker. It stores the token in~/.skyworker/control-tokenand on the Worker. A rerun keeps the same token.Deploy the web client
initdeploys a second Worker,skyworker-app, with the web client for a phone. A failure here leaves a working install with no web client.Set up GitHub
If
ghis logged in,initoffers to use that login. Otherwise it asks for a token.--no-githubskips this step. See GitHub access.Install the handoff skill
initoffers to install a skill for Claude Code and OpenCode on this machine. The skill tells a local agent how to hand a task to a workspace.--no-skillskips this step.
At the end, init prints the Worker URL and the next command.
Check the install
skyworker doctordoctor checks Node, OpenCode, ssh, the Worker URL, the control token, the web client, the Worker, its AI and Browser Run bindings, and the GitHub token. It starts no workspace. Each line starts with ✓, ! or ✗. Fix every ✗ line. The exit code is 1 when a check fails.
Connect
Go to a git checkout and run connect:
cd my-project
skyworker connectThe workspace name comes from the directory name. The first connect clones the origin remote into the workspace and checks out your branch. Your local OpenCode then opens against the workspace.
Run a first task
run hands a task to an agent and returns. The workspace clones from the Git remote. Commit and push your work first.
skyworker run "Add a health check route with a test" --title "Health check"run prints the session id and the commands to follow it:
Started ses_4f2a… in my-project: Health check
Status: skyworker tasks ses_4f2a… --workspace my-project
Wait: skyworker tasks ses_4f2a… --workspace my-project --wait
Follow: skyworker tasks ses_4f2a… --workspace my-project --follow
Open: skyworker connect my-project --session ses_4f2a…Use --follow to watch the agent work, or --wait to block until the task ends. Open attaches your local OpenCode to the session.
You can close the laptop now. The task goes on in the workspace.
Read the result
List your tasks:
skyworker tasksShow the result of one task:
skyworker tasks ses_4f2a… --workspace my-projectThe result record comes from the workspace, not from the words of the agent. It has the state, a summary, the branch, the commits and the pull request. See Run tasks.
To fetch the branch of the task into your checkout:
skyworker tasks ses_4f2a… --workspace my-project --pullNext
- Run tasks: flags, replies, budgets.
- Use Skyworker from a phone: pair a phone.
- Costs: what costs money.