---
title: "Quickstart"
description: "Install Skyworker into your Cloudflare account, check it, and run a first task."
---

> Documentation Index
> Fetch the complete documentation index at: https://skyworker.system3inference.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> **Note**
>
> Skyworker needs a licence key. Keys are not on sale yet.

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

```sh
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

```sh
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:

```sh
skyworker init
```

`init` checks everything before it changes anything. It prints every problem at once, one `Failed: … — fix: …` line each. See [Troubleshooting](https://skyworker.system3inference.dev/docs/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](https://skyworker.system3inference.dev/docs/guides/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

```sh
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`:

```sh
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.

```sh
skyworker run "Add a health check route with a test" --title "Health check"
```

`run` prints the session id and the commands to follow it:

```text
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:

```sh
skyworker tasks
```

Show the result of one task:

```sh
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](https://skyworker.system3inference.dev/docs/guides/tasks/#read-the-result).

To fetch the branch of the task into your checkout:

```sh
skyworker tasks ses_4f2a… --workspace my-project --pull
```

## Next

- [Run tasks](https://skyworker.system3inference.dev/docs/guides/tasks/): flags, replies, budgets.
- [Use Skyworker from a phone](https://skyworker.system3inference.dev/docs/guides/phone/): pair a phone.
- [Costs](https://skyworker.system3inference.dev/docs/concepts/costs/): what costs money.

Source: https://skyworker.system3inference.dev/docs/quickstart/index.mdx
