Workspaces

A workspace groups boxes that belong together. Each workspace has its own shared /wrk drive, its own persistent box homes, and (with secrets) its own credentials — so different projects stay isolated instead of sharing one flat pool.

You always have a default workspace: with no workspace named, everything works exactly as before. Naming one is purely additive.

Using a workspace

The workspace is a prefix on the box name — <workspace>/<box>:

ssh cli@box.hopbox.dev ws create ws1       # create a workspace
ssh ws1/box1:python@box.hopbox.dev         # box "box1" (python) in workspace "ws1"
ssh ws1/box2@box.hopbox.dev                # box "box2" in the same workspace
ssh box1@box.hopbox.dev                    # no prefix → your default workspace

Names are per workspace: ws1/box1 and your default box1 are two different boxes with two different drives and homes.

Managing them

ssh cli@box.hopbox.dev ws ls          # your workspaces + box counts
ssh cli@box.hopbox.dev ls             # all your boxes, grouped by WORKSPACE
ssh cli@box.hopbox.dev ws rm ws1      # remove a workspace (refused if it has boxes)
ssh cli@box.hopbox.dev ws rm ws1 --force    # …or take its boxes with it

Every box command takes a box reference — <workspace>/<box>, a bare name (your default workspace), or an id:

ssh cli@box.hopbox.dev suspend ws1/box1
ssh cli@box.hopbox.dev rm ws1/box1
ssh cli@box.hopbox.dev clone ws1/box1 ws1/box1-copy   # dst inherits the src workspace

Programmatic doors answer the same question: every box in GET /v1/boxes and on hopbox://fleet carries the workspace it is in — absent for your default one, so workspace + name is the reference you'd type back.

What a workspace isolates

Per workspace	Notes
Boxes	names are scoped — ws1/box1 ≠ default/box1.
/wrk drive	each workspace has its own shared drive; boxes in it share it, boxes elsewhere never see it.
Persistent homes	a box's home is scoped to its workspace.
Secrets	set a secret on a workspace and it reaches that workspace's boxes only.

Nothing changes if you don't use them

The default workspace is the flat model you already have — same boxes, same /wrk, same secrets, same commands. A named workspace is an opt-in grouping on top; there's no migration and nothing to relearn.

A default box profile

A workspace can name the box profile its boxes start from, so the boxes in a project do not each have to say it:

ssh cli@host ws profile acme go-dev    # set it
ssh cli@host ws ls                     # WORKSPACE  BOXES  PROFILE
ssh cli@host ws profile acme -         # clear it

It is a default, never an override — precedence is explicit spec > workspace default > nothing, so ssh acme/api:ubuntu-22.04@host still gets the catalog image it names. The default workspace cannot carry one: it has no registry entry, and a default that applied to every box you ever spawn is not a project setting.

The profile is checked when you set it, so a name that is not yours is refused there rather than at every spawn afterwards.