Install on your Mac

Requirements

• • macOS 14 or later.
• • Google Chrome, for browser sessions.

Install

1. 1. Download the DMG from the latest release.
2. 2. Double-click the DMG to mount it.
3. 3. Double-click Install Spaces in the DMG.
4. 4. Installing asks for an admin password. The installer copies Spaces.app to Applications, installs the command-line tools, and sets up the background service that keeps your terminal sessions running after you close the app.
5. 5. Eject the DMG.

First launch

On first launch, Spaces shows only the setup steps that are still pending.

• • Allow Spaces to control Google Chrome. Spaces focuses browser sessions by controlling Chrome, which macOS gates under Automation permission. Choose “Grant Access” and approve the macOS prompt, or “Open System Settings” if Chrome control was denied before; a “Recheck” button re-reads the permission. The step advances on its own once access is granted. If Chrome is not installed, this step does not appear.
• • Coding-agent hooks. Skippable, and offered again later in Settings → Coding Agents. See Agent status.

Command-line tools

Install places the spaces command at /usr/local/bin/spaces. Confirm it is on your PATH:

spaces --version

See the CLI reference for every command.

Updates

The Mac app updates itself. Settings → General → “Receive pre-release updates” is off by default; turning it on means you get each release as soon as it is published, before it is promoted to everyone.

Paired devices update the same way, without ending anything running on them. When a device has a newer Spaces installed than the one it is running, its row shows “update pending” while Spaces applies the update in place; running terminals, processes, and agents keep running throughout.

A device that is too old or too new to talk to shows both versions and the one fix that applies: open Spaces on a remote Mac, use “Check for Updates” on this Mac, or run the install command on a Linux machine (see updating Linux). A Linux device paired over SSH also offers an “Update over SSH” action that runs the same command for you.

Uninstall

To remove Spaces completely:

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/dev.usespaces.spacesd.plist
rm -f ~/Library/LaunchAgents/dev.usespaces.spacesd.plist
rm -rf /Applications/Spaces.app
sudo rm -f /usr/local/bin/spaces /usr/local/bin/spacesd /usr/local/bin/spaces-caddy
sudo rm -f /usr/local/bin/libghostty-vt*.dylib
rm -f ~/.spaces/bin/spaces ~/.spaces/bin/spacesd
rm -rf ~/.spaces ~/spaces

~/.spaces holds the local database; ~/spaces holds any git repos Spaces cloned for you and your workspace worktrees. Leave them alone if you want to keep that state.

Install on Linux

A Linux machine runs Spaces as a remote device. See Remote machines for the install command and pairing.