Skip to content

Quickstart

Install Skyworker into your Cloudflare account, check it, and run a first task.

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 skyworker

If 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 login

The 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 login on this machine. In a terminal, init offers to run it for you when you are not logged in.
  • Set CLOUDFLARE_API_TOKEN to a token with Workers Scripts Write and Workers Containers Write. Or use --token-file <path>.

Then run:

skyworker init

init checks everything before it changes anything. It prints every problem at once, one Failed: … — fix: … line each. See Troubleshooting.

  1. Check the machine and the account

    init checks 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>.

  2. Deploy

    init builds the workspace image and deploys the Worker skyworker. The log is in ~/.skyworker/deploy.log.

  3. Store the control token

    init makes 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-token and on the Worker. A rerun keeps the same token.

  4. Deploy the web client

    init deploys a second Worker, skyworker-app, with the web client for a phone. A failure here leaves a working install with no web client.

  5. Set up GitHub

    If gh is logged in, init offers to use that login. Otherwise it asks for a token. --no-github skips this step. See GitHub access.

  6. Install the handoff skill

    init offers 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-skill skips this step.

At the end, init prints the Worker URL and the next command.

Check the install

skyworker doctor

doctor 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 connect

The 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 tasks

Show the result of one task:

skyworker tasks ses_4f2a… --workspace my-project

The 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 --pull

Next

Type to search…

↑↓ navigate↵ selectEsc close