What Is a Process?
A process is a command you want running whenever the workspace is running — a dev server, a worker, a test watcher, a coding agent. You configure processes on the project; each workspace gets its own copy it can tweak without affecting the project.
- • Spaces gives each process its own terminal window when the workspace launches.
- • Each process runs in a Spaces terminal, so if you close the window the process keeps running and Spaces can reopen the session view without restarting the work.
Shell Commands
Every process command is shell input, like typing into a terminal. Spaces runs the command through your resolved login shell with the workspace environment already exported.
- • Plain commands such as
npm run dev and python manage.py runserver run naturally. - • Composite commands can use
cd, &&, pipes, redirects, and normal shell expansion.
# Env assignment
PORT=$SPACES_WEB_PORT npm run dev
# Braced expansion
PORT=${SPACES_WEB_PORT:-3000} npm run dev
# Directory changes
cd frontend && PORT=$SPACES_WEB_PORT npm run dev
# Pipelines
npm run dev | tee .logs/frontend.log
Spaces validates that the command is non-empty and leaves parsing to your shell.
On Exit
Pick what Spaces should do when a process exits:
- • none — mark it exited and move on.
- • notify — show a macOS notification so you know it died.
- • restart — start it back up automatically.
Environment Variables
Every process runs with the workspace's per-service variables and directory variables in its environment:
SPACES_WEB_PORT, SPACES_API_PORT, ... # assigned port per service
SPACES_WEB_URL, SPACES_API_URL, ... # Caddy URL per service
SPACES_WEB_HOST, SPACES_API_HOST, ... # Caddy hostname per service (no scheme or port)
SPACES_PROJECT_DIR # project directory
SPACES_WORKSPACE_DIR # this workspace's directory
Reference them directly in your command, for example PORT=$SPACES_WEB_PORT npm run dev. The shell expands those variables when the process starts. See Services for how these ports and URLs are assigned and routed.
Editing While Running
- • Add a process — it appears immediately. You can launch it directly if the workspace is already running.
- • Change a command — Spaces asks for restart confirmation because the running process must be relaunched.
- • Change only the name or on-exit policy — Spaces applies the edit immediately when it can.
- • Remove a process — Spaces stops it and closes its terminal window.
Coding Agents
Coding agents run as processes like any other, but they can also report their own lifecycle — started, waiting on you, done — through spaces agent signal. Alerts surfaces those states so you know which agent needs you next.
