---
title: "Workspaces"
description: "Connect to a workspace, pause it, list it, open a shell, copy files and preview a dev server."
---

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

# Workspaces

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:

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

```sh
skyworker pause <workspace>
```

## List and inspect

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

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

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

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

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

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

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

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

```sh
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](https://skyworker.system3inference.dev/docs/reference/cli/#skills) for the other forms.

Source: https://skyworker.system3inference.dev/docs/guides/workspaces/index.mdx
