spaces.yaml

A spaces.yaml file describes a project's setup script, services, processes, and browser sessions, so you can check them into the repo and import them.

Where it lives

Spaces reads spaces.yaml from the project folder: for an existing folder project, that folder; for a cloned repository, the default workspace's checkout on its default branch. Spaces reads it when you add a project, and again whenever you import it into project settings.

Example

version: 1
setup_script: |
  npm install
  cp .env.example .env
stop_script: ""
services:
  - web
processes:
  - name: web
    command: PORT=$SPACES_WEB_PORT npm run dev
    on_exit: none
browser_sessions:
  - name: web
    url: $SPACES_WEB_URL

Keys

Key	Value
`version`	1
`setup_script`	runs before anything else launches
`stop_script`	runs when the workspace stops
`services`	a list of service names
`processes`	a list of `name`, `command`, and `on_exit` (`none`, `notify`, or `restart`)
`browser_sessions`	a list of `name` and `url`

Validation

A version higher than Spaces supports is rejected; omitting it uses the current version.
Every process and browser session needs a name.
Service names must be DNS labels, see Services and URLs.
Keys Spaces does not recognize are ignored.

Import and export

Import previews the file's settings in project settings without saving them. On a Git project, Save offers “Update All Workspaces” or “Project Only” only when the save carries an import; saving without one never rewrites other workspaces. A non-git project has one workspace that shares the project's settings, so every save applies to it directly. Export writes the project's saved settings to spaces.yaml and needs no unsaved edits pending.