Spaces
Download

Services

A service is a named endpoint your project exposes — like web or api. Spaces gives every workspace its own port for that service and routes it to a stable, predictable URL.

What Is a Service?

You configure services on the project, the same way you configure processes and browser sessions. Each service is a unique DNS-safe name — 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 dynamically assigned local port for each service. Two workspaces of the same project never share a port, so you can run several branches of the same app at once without hand-assigning ports or editing .env files.

Stable URLs Through Caddy

A bundled Caddy reverse proxy runs on your Mac and routes each service to a predictable URL:

http://<service>.<workspace-slug>.localhost:7391
  • • The router port is 7391. There is no user-facing setting to change it.
  • • Routing is plain HTTP on that shared port and listens only on loopback addresses — no TLS, certificate, or admin setup, since Chrome and Safari treat *.localhost as a secure context.
  • • Chrome is the supported browser. Firefox does not resolve arbitrary *.localhost names by default.
  • • Caddy routes every service host whether or not it has a browser session attached.

Because each workspace routes through its own hostname rather than a shared localhost port, browser cookies and local storage never bleed between workspaces — logging in on one branch does not log you into another.

Environment Variables

Every process, setup script, and stop script in the workspace runs with these variables for each service — web becomes WEB, admin-ui becomes ADMIN_UI:

SPACES_WEB_PORT   # assigned local port, e.g. 51234
SPACES_WEB_HOST   # routed hostname, no scheme or port
SPACES_WEB_URL    # routed URL, e.g. http://web.my-branch.localhost:7391

Bind your dev server to $SPACES_WEB_PORT and reference $SPACES_WEB_URL directly instead of composing a URL by hand — see Processes for how these variables reach a running command.

Remote & Linux Workspaces

Remote and Linux daemons do not run the Caddy router themselves. When the Mac app observes a running remote workspace with named services, it opens one SSH local-forward per assigned service port and registers Caddy routes on your Mac to those forwards — so the same stable URL works whether the workspace is local or remote.

Remote and Linux workspace processes still receive SPACES_<SERVICE>_URL, so app servers can allowlist the browser-facing host or origin for CORS and framework host checks.

Adding & Removing Services

  • • Adding a service reserves its port immediately — you don't need to relaunch the workspace to use it.
  • • A service's port stays assigned to its workspace until that workspace is deleted, even while the workspace is stopped.
  • • While a workspace is running, its assigned ports are not placeholder-reserved on your machine; if another local process claims one first, resolve the conflict manually before your server binds it.