docs/workspaces.md: the runner side of workspaces, step by step 448568561f2a

# Workspaces: VS Code in a microVM, the runner side

oxygenhub#69, hub spec §13.3. Written 2026-10-17 with Andy's decisions:

build it, **runner side first**; files **lazy from the start**; editor

traffic over a **WebSocket with multiplexing**. This is the plan for the

runner; the hub's part (the workspaces table, the button, the proxy,

commits) follows it.

## What is there today

- Jobs run to their exit under a hard time limit, with a job token that

  lasts at most two hours (hub `JOB_TOKEN_MAX_AGE_MS`).

- A microVM has no network device. Its only traffic is guest-initiated:

  the egress proxy over vsock (`flow-init/src/egress.rs`).

- The runner speaks to the hub in short HTTPS calls; nothing long-lived.

- flow-casfs mounts a state lazily with FUSE, on the host. Firecracker has

  no virtio-fs, so a FUSE mount on the host cannot be handed to a guest.

- The pinned guest kernel (6.1.155) has overlayfs and vsock, but no FUSE.

## The shape

```

browser ──HTTPS/WS──► hub /{owner}/{name}/workspace/{id}/ ──┐

                                                            │ one WebSocket per workspace,

runner ◄────────────────────────────────────────────────────┘ opened by the runner (yamux streams)

  │ vsock (host connects in)

  ▼

microVM: flow-init ─► openvscode-server on 127.0.0.1:3000

         /workspace = overlay(lower: casfs over vsock, upper: scratch disk)

```

## Steps

Each is an issue of its own, and each lands working and tested.

1. **A guest kernel with FUSE.** The same 6.1 kernel and Firecracker's

   guest config, with `CONFIG_FUSE_FS=y`; pinned by BLAKE3 in `flow.toml`

   on earth-1, plex-1 and mars-1. Pipeline jobs are unaffected.

2. **casfs over vsock.** flow-casfs gains a server half: on the host it

   answers lookups, listings and reads for one state over a vsock port of

   the workspace's VM, from the same graph-key cache it uses today. The

   guest half is a small FUSE client in the workspace rootfs. `/workspace`

   is an overlay: the state read-only below, the VM's scratch disk above,

   so edits are plain files. Opening a workspace costs a listing, not an

   export; the target is under a second on the Linux tree.

3. **The workspace rootfs.** openvscode-server (pinned release, its

   checksum checked), `oxy`, the Oxygen VCS extension, a non-root user;

   built and imported like the rust image (`images/workspace`).

4. **The `workspace` job kind.** `Claim` says `kind: "workspace"`. The

   runner keeps the VM until it is told to stop, or the hub's idle limit

   passes, instead of waiting for an exit; it reports liveness and open

   connections every 30 s, and the hub renews the job token while the

   workspace lives. A runner advertises whether it takes workspaces.

5. **The tunnel.** flow-init accepts host connections on a vsock port and

   forwards each to openvscode-server. The runner opens one WebSocket to

   the hub per workspace (`/api/v1/flow/workspaces/{id}/tunnel`, its

   runner token) and carries each browser connection as a yamux stream to

   that port. Works for runners behind NAT and through Cloudflare.

Then the hub (hub spec §13.3): the `workspaces` table and limits, "Open in

workspace" behind a site setting (off), the owner-only reverse proxy for

HTTP and WebSocket into the tunnel, and commits pushed to `ws/{account}/{id}`

and signed by the hub as the account's delegate.

## Downloads this needs

Linux 6.1 sources (kernel.org) and Firecracker's guest config for step 1,

and an openvscode-server release (GitHub, Gitpod) for step 3: each pinned

and checked against its published checksum, as cosign was.