Workspaces

A workspace is a named context within a single SwarmClaw install. Most users only ever need the default workspace; multi-workspace exists so you can label parallel projects or hand-offs without spinning up additional installs.

Status

v1.5.57 ships metadata-only workspaces. The registry, switcher, and CLI commands are in place, but underlying data (agents, sessions, missions, tasks, memory) is shared across workspaces — they're filed under the active workspace label, not isolated by directory.

Per-workspace data isolation (separate DATA_DIR per workspace) is on the roadmap.

Default Workspace

The default workspace is created automatically on first read and cannot be deleted. All existing data sits inside it after upgrade.

{
  "id": "default",
  "name": "Default",
  "description": "Default workspace",
  "color": "#3b82f6"
}

API

GET    /api/workspaces                List all workspaces
POST   /api/workspaces                Create one  (body: { name, description?, color? })
PATCH  /api/workspaces                Update one  (body: { id, ...fields })
DELETE /api/workspaces?id=<id>        Delete one  (default cannot be deleted)

GET    /api/workspaces/active         Get the active workspace
POST   /api/workspaces/active         Set the active workspace  (body: { id })

CLI

swarmclaw workspaces list
swarmclaw workspaces active
swarmclaw workspaces create --json '{"name":"Client A","color":"#10b981"}'
swarmclaw workspaces set-active --json '{"id":"<workspace-id>"}'
swarmclaw workspaces update --json '{"id":"<id>","description":"Renamed"}'
swarmclaw workspaces delete --query id=<workspace-id>

Storage

The workspace registry is persisted at <DATA_DIR>/workspace-registry.json. The active workspace id is part of the registry so it survives restarts.