Installation

Installation

How to get ClusterSpace running on your machine, from a fresh clone to a packaged build.

TL;DR

git clone https://github.com/mtecnic/clusterspace.git
cd clusterspace
npm install
npm run rebuild
npm run dev

If npm run rebuild succeeds and npm run dev opens a window, you're done. If it doesn't, see Troubleshooting build failures below.

---

Prerequisites

	Version	Why
Node.js	20 or newer	Electron 31 + native modules
Git	any recent	Source clone
Build toolchain	OS-specific (see below)	node-pty compiles native bindings
tmux (on remote hosts only)	2.x or newer	Optional — only needed for SSH session persistence

OS-specific build toolchain

Windows

• Visual Studio Build Tools 2022 with the "Desktop development with C++" workload
• (Recommended) windows-build-tools is no longer required for modern Node, but VS Build Tools is.

macOS

• Xcode Command Line Tools: xcode-select --install

Linux

• build-essential, python3, and the Electron runtime dependencies for your distro. On Debian/Ubuntu:

  sudo apt install build-essential python3 libnss3 libatk1.0-0 libatk-bridge2.0-0 libgtk-3-0 libgbm-dev

---

Install

git clone https://github.com/mtecnic/clusterspace.git
cd clusterspace
npm install

npm install will install all JS dependencies, then electron-builder install-app-deps runs automatically as a postinstall step and rebuilds native modules against the bundled Electron version.

If that postinstall fails (most commonly on Windows without VS Build Tools), run npm run rebuild manually after fixing the toolchain.

---

Run in development

npm run dev

Vite serves the renderer on http://localhost:5173; Electron launches automatically and points at it. The main process restarts when you edit files in src/main/ or src/preload/; the renderer hot-reloads when you edit files in src/renderer/.

If the window opens to a black screen, check the DevTools console (Ctrl+Shift+I) and the terminal where you ran npm run dev for errors.

---

Build a distributable

npm run build      # type-check + bundle (output in dist/ and dist-electron/)
npm run dist       # build + package for your current platform via electron-builder

The packaged installer / app lands in dist/ after npm run dist finishes (typically dist/ClusterSpace-Setup-1.0.0.exe on Windows, .dmg on macOS, .AppImage on Linux).

---

Troubleshooting build failures

node-pty fails to compile (Windows)

• Verify VS Build Tools 2022 is installed with the "Desktop development with C++" workload (not just the SDK).
• Verify you ran npm install from a fresh cmd.exe or PowerShell window opened after installing VS Build Tools, so PATH picks up the new tooling.
• Try npm run rebuild explicitly — it forwards to electron-rebuild -f -w node-pty.

node-pty fails to compile (macOS)

• Run xcode-select --install and accept the EULA prompt.
• If the bindings still fail, delete node_modules/, then npm install again.

Cannot find module '@xterm/xterm' or similar after pull

• Run npm install — the lockfile changed.

Black window on launch

• Vite probably didn't start cleanly. Look at the terminal output for port conflicts (5173 in use), or run lsof -i :5173 (macOS/Linux) / netstat -ano | findstr 5173 (Windows) and kill the stray process.

Electron-rebuild hangs

• Delete node_modules/, package-lock.json, then npm install from a clean state.

More fixes in Troubleshooting.

---

Where ClusterSpace stores data

On first launch, ClusterSpace creates clusterspace-data/ under your Electron userData directory:

• Windows: %APPDATA%\ClusterSpace\
• macOS: ~/Library/Application Support/ClusterSpace/
• Linux: ~/.config/ClusterSpace/

If you previously had Fleet Term (the old name) installed, the legacy fleet-term-data/ is auto-migrated on first launch — see Data-Storage-and-Migration.

---

See also

• Quick-Start — five-minute tour of the app
• Troubleshooting — runtime errors and fixes
• Contributing — dev workflow for hacking on the app