Install SpaceSpider on macOS

SpaceSpider ships a signed and notarized DMG for macOS with universal binaries that run natively on Apple Silicon (M1, M2, M3, M4) and Intel. This page walks you through the install, first launch, and the prerequisites you need before your panes start talking to Claude Code, Codex, Qwen, or Kimi.

System requirements

• macOS 12 Monterey or newer. macOS 14 Sonoma or newer is recommended.
• Apple Silicon or Intel x64 processor.
• 4 GB of RAM minimum; 8 GB recommended for four AI CLIs running at once.
• 200 MB of free disk space for the app.
• Command Line Tools for Xcode, which git and most npm-installed CLIs depend on.

If you have never installed the Command Line Tools, run this once and accept the prompt:

xcode-select --install

Install Node.js and the AI CLIs

The app itself does not need Node to run, but every AI CLI you want to drive does. The fastest clean install on macOS is Homebrew:

brew install node

Then install the AI CLIs you want. Pick whichever combination fits your workflow:

npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
npm install -g @qwen-code/qwen-code
npm install -g @moonshot/kimi-cli

Confirm each one is on your PATH:

claude --version
codex --version
qwen-code --version
kimi --version

SpaceSpider re-runs these which lookups every time you open the CLI picker, so you can install new CLIs after the app is already running.

Download and mount the DMG

1. Download SpaceSpider-universal.dmg from the downloads page.
2. Double-click the DMG to mount it.
3. Drag SpaceSpider.app into /Applications.
4. Eject the DMG.

The app is signed with the SpaceSpider developer ID and notarized by Apple, so Gatekeeper will let it launch without the manual right-click workaround.

First launch and Gatekeeper

Launch SpaceSpider from Launchpad or Spotlight. If you previously downloaded a pre-release build, macOS may remember the quarantine flag and show "SpaceSpider cannot be opened because the developer cannot be verified". Clear the flag manually:

xattr -dr com.apple.quarantine /Applications/SpaceSpider.app

Re-launch and the warning will be gone. Subsequent launches never prompt.

Grant Full Disk Access if your project lives under a protected path

macOS restricts app access to certain directories such as ~/Documents, ~/Desktop, ~/Downloads, and iCloud Drive. The first time SpaceSpider tries to spawn a PTY with a cwd under one of those folders, macOS shows a Files and Folders permission prompt. Approve it.

If you skipped the prompt by accident, add SpaceSpider manually:

1. Open System Settings > Privacy & Security > Files and Folders.
2. Find SpaceSpider and grant access to the relevant folders.

If you want a single switch, use Full Disk Access in the same pane and toggle SpaceSpider on.

First space on macOS

1. Launch SpaceSpider.
2. Click New Space on the home view.
3. Pick a project folder using the macOS folder picker.
4. Give the space a short name.
5. Choose a grid size (2 or 4 panes is a reasonable starting point).
6. Assign an AI CLI to each pane. Tiles with a green dot are already installed.
7. Click Create.

The grid opens, each pane spawns its CLI in your project directory, and you are ready to work. For a slower walkthrough, see Create Your First Space.

Configure the default shell

The shell pane on macOS runs $SHELL by default, which is usually /bin/zsh on macOS 12 and newer. If you want fish, bash, or a pinned zsh, export SPACESPIDER_SHELL before launch:

launchctl setenv SPACESPIDER_SHELL /opt/homebrew/bin/fish

Or in your shell profile:

export SPACESPIDER_SHELL=/opt/homebrew/bin/fish

Relaunch SpaceSpider and new shell panes will use your preferred shell.

Apple Silicon vs Intel

The universal DMG contains both slices. On Apple Silicon, the Rust backend runs natively in arm64. On Intel, it runs as x64 without Rosetta. You can verify which binary your Mac is running:

file /Applications/SpaceSpider.app/Contents/MacOS/SpaceSpider

The output lists both architectures for the universal build. macOS loads the correct slice automatically.

Auto-updates

SpaceSpider checks for signed artifacts on launch and daily after that. When an update is ready, the top bar shows an unobtrusive banner. Clicking it downloads the new DMG contents, verifies the signature against the publisher key, swaps the bundle in place, and prompts you to relaunch. See Updating SpaceSpider for the full mechanism.

Uninstall cleanly

To remove SpaceSpider and its data:

1. Quit the app.
2. Drag SpaceSpider.app from /Applications to the Trash.
3. Remove the app support directory if you want a clean slate: rm -rf ~/Library/Application\ Support/SpaceSpider.

That directory holds spaces.json and your license record. Your project folders and globally installed AI CLIs are untouched.

Troubleshooting

• "The app is damaged and can't be opened": macOS is applying quarantine incorrectly. Run the xattr -dr com.apple.quarantine command above.
• Panes hang on a black screen: the WebKit process did not start. Force-quit SpaceSpider, reboot, and try again.
• Claude Code pane exits with "login required": run claude login in Terminal once to seed the credential, then restart the pane.
• Slow first launch on M-series Macs: macOS is verifying the signature. First launch adds up to 20 seconds; subsequent launches are instant.

A deeper list is in Troubleshooting Common Issues.

Frequently asked questions

Is there a Homebrew cask?

A community cask is under review. Install the DMG for now to guarantee signed auto-updates.

Does SpaceSpider run on macOS 11 Big Sur?

No. The minimum is macOS 12 because the bundled WebKit and Tauri 2 runtime require it.

Can I run it in full-screen Space?

Yes. The grid view is designed for full-screen and uses Cmd+Ctrl+F to toggle.

Does it support macOS Shortcuts or Raycast deep links?

Not yet. A spacespider:// URL scheme is on the roadmap.

How do I migrate my spaces between Macs?

Copy ~/Library/Application Support/SpaceSpider/spaces.json to the new Mac before first launch and your spaces will appear in the home view.

Related reading

• Getting Started with SpaceSpider
• Using Claude Code in SpaceSpider
• Updating SpaceSpider