Workspace
Workspaces
A workspace is Swarm’s saved project context. It gives a folder a name, keeps optional linked directories, replication links, and a workspace theme, and lets new sessions start with the same workspace identity from the terminal UI or Desktop.
Saved context
A workspace is metadata around your folder, not a copy of your project.
Swarm records the workspace path, display name, optional theme, linked directories, and any remote/container replication links created by attach or deploy flows. Sessions then carry that workspace path and workspace name so agents, history, and UI surfaces agree on the active project.
Removing a workspace from Swarm removes saved workspace metadata only. It does not delete the folder or files on disk.
By design, workspace file tools are scoped to the active workspace and linked directories. Agents should not be able to inspect unrelated paths through those tools; if an agent has broad bash access, it may be able to work around that boundary. For the strongest filesystem protection, run Swarm in a container.
Fields
What Swarm tracks for a workspace
pathThe canonical folder path Swarm opens for the workspace.workspace_nameThe human-readable name shown in workspace lists, session headers, and routes.directoriesOptional linked directories attached to the workspace context.replication_linksRemote/container attach metadata for bundled or managed workspace copies on child swarms.theme_idAn optional workspace theme override. Blank means inherit the global theme.worktree settingA workspace-scoped setting used by new sessions when automatic worktrees are enabled.Remote and container links
Remote deploy and local container attach can add workspace replication links.
A normal workspace still points at a local folder. When a local container child or remote child swarm is attached with workspace payloads, Swarm can store a replication link on the source workspace. The link records the target swarm, target workspace path, whether the copy is writable, and whether managed sync is enabled.
Remote deploy builds Git-tracked workspace payload archives locally, copies them over SSH, and records remote links after the child is attached. Target availability still depends on attach status and a backend URL; offline targets should show as unreachable rather than silently becoming local workspaces.
Commands
Terminal workspace commands
/workspace/workspaces is an alias./workspace save [path|#n]/workspace select <name|#n>/workspace scan [query]/add-dir [path]Temporary folders
You can use a folder before saving it as a workspace.
Desktop can open a local folder temporarily, then promote it to a saved workspace later. A temporary folder gives the current window a workspace path, but it does not create saved workspace metadata until you choose to save it.
Saved workspaces are the durable path: they appear in the launcher, can carry linked directories, can be reordered, and can have workspace-level theme and worktree settings.
TUI and Desktop
Both surfaces manage the same workspace state.
Terminal UIUses /workspace, /workspaces, /workspace save, /workspace scan, and /add-dir to open the manager, save folders, and select workspaces.DesktopIs launcher-based. Starting swarm --desktop from a folder does not make that terminal cwd the active workspace; choose a saved workspace, create one, or use a temporary folder from the launcher.Shared runtimeBoth surfaces call the same backend workspace APIs, so the active workspace is runtime state, not a UI-only preference. Remote and container links are stored with that same workspace record.The terminal UI can follow the directory you launched it from. Desktop is different by design: it always starts from the workspace launcher rather than opening directly into the shell cwd.