Workspaces

What Is a Workspace?

A workspace is one stream of work — a feature, a bug fix, an experiment. It belongs to a project, has its own directory (a git worktree for Git projects), and keeps its own copy of the project's processes, browser sessions, and services.

Creating a Workspace

Open the New Workspace form from the + on any project or workspace row, or press cmd+n. For a Git project you'll fill in:

• • Title — the display name in the sidebar.
• • Branch — pick an existing branch or enter a name to create a new one.
• • Base branch — the base for a new branch. Defaults to the project's default, falling back to main or master.
• • Directory name — the folder name for the worktree. Auto-generated, editable later.
• • Notes — optional context you can edit any time or ask a coding agent to keep in sync with the work.

For a non-Git project, the workspace uses the project directory itself and doesn't need a branch.

Per-Workspace Settings

A new workspace inherits the project's processes, browser sessions, and services. From there, each workspace edits its own copy — the project's templates stay unchanged.

• • Double-click the title, branch, or notes to rename them inline. Escape or click away to cancel.
• • Renaming the branch inline renames the underlying git branch.
• • Add, remove, or rename services per workspace.
• • Edit a process command while the workspace is running and Spaces asks to confirm, then restarts just that process.
• • Add a browser session and it opens as a Chrome tab when you focus it.
• • The GUI is the place to edit workspace settings after creation. The CLI stays focused on workspace creation, launch, and agent events.

Services

Name the services your project uses with unique lowercase DNS labels (for example web, api) and Spaces gives each workspace its own port per service plus a stable URL http://<service>.<workspace>.localhost:7391 routed through a bundled Caddy proxy. Two workspaces can run the same project at the same time without fighting over a port.

• • Each service is exposed as SPACES_<SERVICE>_PORT, SPACES_<SERVICE>_HOST, and SPACES_<SERVICE>_URL to every workspace process, plus the setup and stop scripts.
• • Remote Linux workspace services keep their daemon-local port, and the Mac app forwards that port over SSH when a browser session targets the service URL.
• • Spaces keeps each port assignment pinned to the workspace until it is deleted.
• • Stopped workspaces hold placeholder reservations for assigned ports; running workspaces release those placeholders so processes can bind normally.

Workspace: bugfix/login-timeout
SPACES_WEB_PORT=20001
SPACES_WEB_URL=http://web.login-fix-a3f9c2d1847b.localhost:7391
SPACES_API_PORT=20002

Environment Variables

Every workspace process, setup script, and stop script runs with:

• • Per-service variables (for example SPACES_WEB_PORT=20001, SPACES_API_PORT=20002, and the matching SPACES_WEB_HOST/SPACES_WEB_URL, SPACES_API_HOST/SPACES_API_URL). Reference a service's SPACES_<SERVICE>_URL directly rather than composing a URL by hand.
• • SPACES_PROJECT_DIR — the project directory.
• • SPACES_WORKSPACE_DIR — this workspace's directory.

Switching Between Workspaces

Selecting another workspace swaps the whole context — its windows and processes all follow you.

• • cmd+alt+= from anywhere brings Spaces forward; pick the workspace you want.
• • Inside Spaces, cmd+alt+] / cmd+alt+[ step between workspaces.
• • cmd+1 through cmd+0 open or focus a specific target of the selected workspace.
• • Click any workspace in the sidebar or window row in the workspace run tab to jump directly.