Projects

What Is a Project?

A project points at a directory on your Mac. If the directory is a Git repo, Spaces treats each workspace as a branch worktree. Otherwise, each workspace points at the project directory directly.

Project Settings

• • Directory — the project folder. Spaces uses the folder name as the display name.
• • Setup script — runs once when a new workspace is created. A good place for npm install or copying a shared .env file into the workspace.
• • Stop script — runs whenever a workspace is stopped (including on restart and delete), after Spaces shuts its processes down. Use it to tear down any extra services the workspace left behind.

Project Templates

You configure processes, browser sessions, and services once on the project. New workspaces start from those templates. Each workspace can edit its own copy without affecting the project or other workspaces.

• • Processes — commands Spaces runs alongside the workspace (servers, workers, coding agents).
• • Browser Sessions — URLs tied to a workspace; each opens as a Chrome tab when you focus it.
• • Services — unique DNS-safe names like web and api. Spaces assigns each workspace its own port per service and a stable URL through a bundled Caddy proxy, so two workspaces never clash.

Adding a Project

Add a project from the app by pointing at a local directory or pasting a Git URL. For a Git URL, Spaces clones into ~/spaces/repos. Either way, Spaces creates a default workspace for you automatically.

Default Workspace

Every project has a default workspace:

• • Git projects — the default workspace tracks main or master.
• • Non-Git projects — the default workspace points at the project directory.
• • The default workspace can't be deleted on its own but you can delete a project entirely.

Removing a Project

• • Spaces cleans up the project's workspaces and their worktree directories.
• • If Spaces cloned the repo (via Git URL), the clone under ~/spaces/repos is removed too.
• • Directories you pointed Spaces at yourself are left alone.