Documentation
Spaces in five minutes.
A quick mental model for how Spaces helps you run and switch workspaces during parallel development.
Glossary
Core terms.
The small vocabulary you need to get oriented with Spaces.
- Project
- A codebase you configure once so new workspaces start with consistent behavior.
- Workspace
- An isolated stream of work for a feature, fix, or experiment consisting of git branch, processes, terminal and browser windows.
- Process
- Commands you want running with the workspace, like app servers or agents.
- Browser Session
- URLs you want tied to a workspace (e.g. localhost:3000, github.com/owner/repo) so you can return to them quickly.
- Service
- A named process (like web or api) that gets its own reserved port per workspace and a stable URL through the bundled proxy — so parallel workspaces never fight over the same local port.
- Worktree
- A Git feature that checks out a branch into its own directory, so multiple branches can be open at once. Spaces gives each workspace its own worktree.
Overview
Docs Overview
These pages cover the most common user questions and operational workflows from setup through troubleshooting.
Installation & Setup
Get Spaces installed, its dependencies in place, and your environment verified, then grant permission to control Google Chrome on first launch. Includes installing and updating the daemon on Linux, plus the SSH access, network reachability, and background-service requirements a remote machine or cloud VM has to meet before it can pair. If the Editor shows a persistent "Live refresh off" notice naming the device's inotify watch limit, raise fs.inotify.max_user_watches on that device.
Read page 02Getting Started
Connect your first project and launch a workspace in under five minutes.
Read page 03Projects
Configure a codebase once so every workspace you create starts with its processes running and its named services reachable at stable per-workspace URLs, with browser sessions ready to focus.
Read page 04Workspaces
Create, name, and switch between isolated streams of work, each with its own git branch, windows, processes, and settings.
Read page 05Workspace Lifecycle
Understand how workspaces move between stopped and running, and how deleting removes one, across the GUI and the minimal CLI runtime flow.
Read page 06Services
Declare named services once and reach each at a stable per-workspace URL through a bundled Caddy proxy — no manual port assignment, no cookie collisions between workspaces.
Read page 07Processes
Run servers, workers, and coding agents alongside each workspace as terminal-style shell commands with named-service and Spaces directory variables.
Read page 08Browser Sessions
Attach Chrome URLs to a workspace so the pages you need are one direct shortcut away while unopened sessions stay out of window cycling, and open the same sessions in an in-app web view from your iPhone.
Read page 09Window Management
Spaces tracks workspace Chrome tabs and terminal panes so direct shortcuts can open or focus targets and cycling stays inside already-open windows.
Read page 10Coding Agents
Track Claude Code, Codex, opencode, and other coding agents per workspace, and drive several of them from a single terminal — list, spawn, annotate, subscribe for blocked/done alerts, send keystrokes, and kill. Spaces offers to install lifecycle hooks for detected agent CLIs so each session reports its state automatically.
Read page 11Agent Orchestration
Talk to one agent to get all your work done: a lead agent spawns children in isolated worktrees across harnesses, models, and machines, and coordinates them to a verified finish. Includes the copy-paste orchestrator prompt.
Read page 12Automations
Schedule a coding agent with a prompt, or run any shell command, on your Mac or a paired Linux box — manually or on a schedule, even when Spaces is closed. Watch runs live and replay them later.
Read page 13Keyboard Shortcuts
Jump between workspaces, focus windows, and trigger common actions with shortcuts you can configure, plus the fixed keys that zoom terminal text.
Read page 14Troubleshooting
Fix common launch, capture, process, and focus issues with step-by-step recovery playbooks.
Read page 15Cookbook Guides
Copy-and-adapt project setup recipes for common stacks.
Read page 16CLI Reference
Use the spaces CLI for same-machine workspace actions, pairing links, Spaces terminal sessions, text and byte terminal input, owner-seeking terminal windows, and stopping a workspace or a single terminal session.
Read page 17Model Context Protocol
Connect an MCP client such as Claude Code, Codex, or opencode to the spaces mcp server so it can list and drive your projects, workspaces, and Spaces terminals.
Read page 18iOS App
Pair the Spaces iOS app directly with a Mac or Linux device — no desktop app in between — to browse live terminal sessions, watch coding agents, run workspace processes, open browser sessions in an in-app web view, and create workspaces from your phone, or tour the app with sample data in Demo Mode before you pair.
Read page