Skip to content

Workspaces

Connect to a workspace, pause it, list it, open a shell, copy files and preview a dev server.

A workspace is one Cloudflare Container with a disk that pauses to a snapshot. Each git checkout has one workspace. The name comes from the directory: lowercase, with each other character changed to -. The directory My App gives the workspace my-app.

Connect

From a git checkout:

skyworker connect

connect wakes or creates the workspace and opens your local OpenCode against it. OpenCode 2 must be on this machine. doctor checks it.

The first connect clones the origin remote into the workspace over HTTPS. It checks out your branch and copies your git user.name and user.email. A branch that is not pushed starts from the default branch. Push it first to bring your commits. Later connects restore the snapshot, so installed packages and uncommitted work are still there.

Flag Meaning
--dir <path> The project directory in the workspace. The default is /home/user/project.
--repo <url> The git remote to clone when the workspace has no snapshot yet.
--branch <name> The branch to check out.
--no-attach Print the server URL instead of opening OpenCode.
--skills <a,b|all> Copy these skills from this machine into the workspace first. Off by default.
--continue, -c Open the last session of the workspace.
--session, -s <id> Open that session.

To name a workspace, pass it: skyworker connect <workspace>.

When you quit OpenCode, it prints Continue opencode -s ses_…. Do not use that command. It starts a local session. The session lives in the workspace. Use skyworker connect --continue or skyworker connect --session <id>.

When a workspace pauses

A workspace pauses after idlePauseMinutes (default 20) with no use. Use is a request through the Worker, output of a terminal in the workspace, an agent that works, or a job that runs. A session that waits for an answer is not work.

On a pause the disk is saved to a snapshot. The container stays warm for warmMinutes (default 10), then stops. Compute billing stops with it. maxAwakeHours (default 12) pauses a workspace that is awake that long, also while it works.

A paused workspace keeps its disk, not its processes. A dev server that the agent started is gone after a pause. The work it finished is not.

To pause a workspace now:

skyworker pause <workspace>

List and inspect

skyworker list
skyworker status <workspace>
skyworker status
skyworker sessions
skyworker logs <workspace> --lines 200
  • list shows the workspaces this machine connected to: state, since when, when the snapshot expires, and the repository. A ! marks a snapshot that expires within two days. A connect saves it.
  • status <workspace> shows one workspace. status alone shows the install: Worker URL, size and idle settings.
  • sessions lists the sessions of every harness across your workspaces. What waits for you comes first. * marks a session that is not read yet. It wakes nothing. sessions <workspace> or --live asks the workspace itself.
  • logs prints the redacted opencode serve log. The default is 100 lines. The most is 1000.

Delete and rebuild

skyworker delete <workspace>
skyworker rebuild <workspace>

delete destroys the workspace. Its snapshot data expires on its own. The next connect starts again from the image.

A snapshot is the whole disk, tools included. A restore keeps the tools of the image the workspace first booted, also after skyworker upgrade. status says when the image is older than the deployed one. rebuild moves the workspace onto the deployed image and keeps /home/user. It stops the agent. Packages installed outside /home/user with apt are not carried.

Open a shell

skyworker shell <workspace>

The shell runs in tmux inside the workspace. Closing the terminal does not stop what runs there. Detach with ctrl-b d. A dropped connection also detaches. Run the same command to reattach. --session <name> picks another tmux session. The default is main.

Use SSH

skyworker ssh <workspace>
skyworker ssh <workspace> -- ls -la
skyworker ssh-config <workspace> >> ~/.ssh/config

ssh needs the system ssh. The connection goes over the Worker. No port is open. ssh-config prints a Host block so ssh, scp and herdr reach the workspace by name.

Copy files

skyworker cp app:build ./build
skyworker cp ./fixtures app:test/
skyworker cp app:export.json.gz api:data/

A side is <workspace>:<path> or a local path. A workspace path is relative to the checkout, or starts with / or ~ inside /home/user. An existing folder, or a path that ends in /, takes the item inside it. --force replaces a target that exists.

  • A copy from this machine is at most 100 MB.
  • One copy is at most 4 GB and 200,000 entries.
  • A paused workspace wakes. It counts toward maxRunning and pauses again when idle.
  • The target changes only when the copy ends.

Use the store

The store is an R2 bucket of the install. It is off unless the store setting is true. Its files outlive a pause and a delete. R2 bills for them.

skyworker cp app:export.gz store:
skyworker cp store:export.gz api:
skyworker store
skyworker store rm export.gz

store --prefix <text> lists only the names that start with it. The store holds files, not folders.

Preview a dev server

The agent starts a dev server in the workspace. Open it on your machine:

skyworker preview 3000
skyworker preview app 3000 5173

The first form uses the workspace of this directory. The second names a workspace and two ports. The port is forwarded over the SSH of the workspace for as long as the command runs. Ctrl-C stops it. Nothing is public. The app is at http://localhost:<port>. --no-open does not open the browser.

Flag Meaning
--web Use a URL on the Worker, behind a one-time sign-in link. It needs no ssh here. The dev server must listen on 0.0.0.0.
--public Make a URL that needs no password, until --stop. It needs the control token.
--stop Remove the public URL of the port, or of every port without one.
--list List the public URLs of the workspace.
--json Print one JSON document with the Worker URL and its sign-in link.

Anyone who has a public URL can open that port while the workspace is awake. There is none until you run --public.

Open a browser session

skyworker browse <workspace>

browse opens a Browser Run session for the workspace and prints its address. Billing is per browser hour on your Cloudflare account. A session closes after 10 minutes without activity.

Copy skills

A workspace starts with the skills of OpenCode only. Copy skills from this machine by name:

skyworker skills
skyworker skills push a b
skyworker skills default a b

A skill is a folder with a SKILL.md. A copy stays on the disk of the workspace and in its snapshots. .git, node_modules, .env and key files are not copied. See the CLI reference for the other forms.

Type to search…

↑↓ navigate↵ selectEsc close