A service is a named endpoint your project exposes, like web or api. Spaces gives every workspace its own port for that service and a stable, predictable URL.
You declare services on the project, the same way you declare processes and browser sessions. Each service name is a DNS label: lowercase letters, digits, and hyphens, starting and ending with a letter or digit, up to 63 characters, such as web, api, or admin-ui. Every workspace gets its own port for each service, so two workspaces of the same project never share one.
Ports are assigned from 20000 to 30000, for example 24817. A service's port stays assigned to its workspace for the workspace's life, including while it is stopped, and is released only when the workspace is deleted. Adding a service reserves its port right away, so you do not need to relaunch the workspace to use it. New assignments skip ports another program is already listening on.
A port that is already assigned is never moved. If another program holds it when you start a stopped workspace (with Start or Restart), the workspace starts anyway and Spaces tells you which service's port is held and, when it can tell, by which program and pid, so you can stop that program.
Your process reads its port from SPACES_<SERVICE>_PORT, see Environment variables. While a workspace is running, its assigned ports are not held open; if another process on the device that runs the workspace (this Mac, or the paired Mac or Linux machine that owns it) claims one before your server binds it, resolve the conflict on that device.
Each service routes to a predictable URL:
http://<service>.<workspace-slug>.localhost:7391The port is 7391, with no setting to change it. Routing is plain HTTP on that port and listens only on your Mac, since Chrome treats *.localhost as a secure loopback address and needs no certificate or setup for it.
The workspace slug is built from the branch name for a Git workspace (for example login-fix-a3f9c2d1847b) or the project name for a folder project, followed by a hash of the workspace's id; the home workspace (~) uses that same form, for example home-1a2b3c4d5e6f. Because each workspace gets its own hostname, cookies and local storage never carry over between workspaces: logging in on one branch does not log you into another.
Chrome is the supported browser: it resolves *.localhost names without configuration. Firefox does not resolve arbitrary *.localhost names by default. A browser session opens a service URL in Chrome when you focus it.
A remote Mac or Linux machine does not route service URLs itself. When you focus a browser session for a service running on a remote workspace, your Mac forwards that service's port to itself over SSH and routes it at the same stable URL, so the URL works the same whether the workspace is local or remote. Remote workspace processes still receive SPACES_<SERVICE>_URL, so a server can allowlist the browser-facing host for CORS or framework host checks.
Add or remove services in project or workspace settings, or in spaces.yaml.