Skip to content

How it works

The parts of Skyworker and how a task moves through them.

Skyworker has no hosted part. Every part runs on your machine or in your Cloudflare account.

The parts

Part Where it runs What it does
CLI Your machine skyworker commands. It deploys the install and talks to the Worker.
Installer Your machine The npm package skyworker. It stores your licence key, gets the signed build and runs it.
Worker Your Cloudflare account The control API. It owns the workspaces, the session index, the secrets and the egress rules.
Web client Your Cloudflare account, as the Worker <name>-app The inbox for a phone or a browser.
Workspace Your Cloudflare account One Cloudflare Container with a disk that pauses to a snapshot.
Bridge In each workspace One process that holds the harness adapters. It serves one HTTP API to the Worker.
Harness In each workspace The agent: OpenCode, Claude Code or Codex.

Sessions and tasks

A session is one conversation with an agent in one harness. It is the only record of Skyworker. A task is a session with a task contract: a goal, a start commit, a closing instruction and an optional schema. run sets the contract.

The session index is the list of all sessions of all workspaces. The inbox is the view of that index for a person. It shows one row for each session, with waiting first. The attention state of a session is working, waiting, idle, done, failed or stopped. A session is unread when its attention state changed and you did not read it.

How a task moves

  1. You run skyworker run "<task>" in a git checkout.
  2. The CLI checks that the workspace can see your work. It then asks the Worker to wake or create the workspace.
  3. The workspace clones from your Git remote. The Worker writes the bridge into it at each wake.
  4. The bridge starts a turn of the harness. The agent works. You can close the laptop.
  5. The Worker reads the result record from the workspace: the state, the branch, the commits, the changed files and the pull request. It does not use the words of the agent.
  6. When the task leaves working, the Worker can POST the record to your notify URL, and the phone can notify you.

Life of a workspace

  • A workspace wakes on connect, run, a reply, shell, ssh or a wake from a paired device.
  • It stays awake while it is in use. After idlePauseMinutes with no use, it saves its disk to a snapshot.
  • The container stays warm for warmMinutes, then stops.
  • Cloudflare drops a snapshot 30 days after its creation or last restore. Three days before that, the Worker restores a paused snapshot for a few seconds. That starts a new 30 days. The setting is snapshotRefreshDays.
  • A paused workspace keeps its disk, not its processes.

See Limits and Costs.

Your machine and the workspace

Your machine keeps state in ~/.skyworker: the install record, the control token, a file for each workspace and your SSH key. The workspace keeps the repository, the tools and the sessions. A workspace never holds the control token, a model key or the GitHub token. See Security.

Type to search…

↑↓ navigate↵ selectEsc close