Runtime State
A workspace is always in one of two runtime states. Runtime health (a failed process, a stale window) surfaces as a warning on top of these states rather than as a separate state.
- • Stopped — the workspace exists but nothing is running. This covers both a workspace Spaces has never launched and one it explicitly stopped; either way it is directly launchable.
- • Running — Spaces has started its processes. Browser sessions stay configured but open on demand when you focus them.
Visibility is separate from runtime state. Independently of being running or stopped, a workspace can be hidden, which collapses it into the Hidden section at the bottom of the sidebar and leaves it there until you unhide it.
Create
On create, Spaces copies the project's templates into the workspace, reserves its named ports, and runs the setup script. Git projects also get a branch worktree. If you named a branch that doesn't exist yet, Spaces creates it from the base branch.
Launch
Launching a stopped workspace:
- • Starts each configured process in its own Spaces terminal window.
- • Leaves browser sessions unopened until you explicitly focus them.
- • Remembers those windows so you can jump back to any of them by keyboard shortcuts.
Update While Running
- • Add a process — it appears immediately with a non-running status; launch it when you're ready.
- • Edit a process command — Spaces asks you to confirm, then restarts just that process.
- • Add a browser session — it appears immediately and opens as a Chrome tab when you focus it.
Stop and Restart
- • Stop gracefully interrupts each process, then escalates if needed.
- • Spaces closes the terminal and browser windows it opened for the workspace.
- • The stop script runs after the processes are down.
- • Restart is stop followed by launch.
From a workspace directory, spaces workspace start is the concise, convergent way to make sure it is running, and spaces workspace restart stops and relaunches it unconditionally. Scripts and paired-device commands can pass --workspace <id> explicitly. Start launches whichever configured processes aren't already running — fresh ones and exited ones alike — and leaves already-running processes, ad hoc terminals, and coding-agent sessions untouched; use the Mac app to foreground tracked workspace windows.
Delete
Delete retires a workspace for good: it stops the workspace, releases its named ports, removes its Git worktree, and deletes the workspace and its settings from Spaces. Its branch name and checkout directory are free to use again right away. The branch itself is kept unless you tick the local- or remote-branch deletion boxes in the confirmation. The default workspace can't be deleted — delete the project to remove it.
