Install SpaceSpider on Linux

SpaceSpider supports Linux through two formats: a portable AppImage that runs on any modern glibc-based distro, and a .deb package for Debian, Ubuntu, and their derivatives. Both builds use the same signed artifacts behind the auto-updater. This page walks through each path, plus the library prerequisites the Tauri 2 WebView needs.

Supported distros

• Ubuntu 22.04 LTS, 24.04 LTS, and 25.04.
• Debian 12 Bookworm and later.
• Fedora 39 and later.
• Arch Linux rolling (via AppImage).
• Most glibc 2.35+ distros via AppImage.

Musl-based distros such as Alpine are not supported. WebKitGTK 4.1 is required. On older Ubuntu LTS releases you may need to add the Tauri PPA to pull in a current WebKitGTK.

Install system prerequisites

Tauri 2 needs WebKitGTK for the WebView and a handful of supporting libraries. On Debian and Ubuntu:

sudo apt update
sudo apt install libwebkit2gtk-4.1-0 libayatana-appindicator3-1 libssl3 librsvg2-2

On Fedora:

sudo dnf install webkit2gtk4.1 libappindicator-gtk3 openssl-libs librsvg2

On Arch:

sudo pacman -S webkit2gtk-4.1 libappindicator-gtk3 openssl librsvg

Install Node.js and AI CLIs

Use your distro package manager or nvm for Node. nvm keeps global npm installs out of /usr:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install --lts

Then install the AI CLIs you want:

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:

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

SpaceSpider runs which for every supported CLI when you open the picker, so as long as these commands resolve on your $PATH, the tiles in the picker will show a green dot.

Option 1: Install via AppImage

The AppImage is the fastest way to try SpaceSpider because it is a single portable file.

1. Download SpaceSpider-x86_64.AppImage from the downloads page.
2. Make it executable: chmod +x SpaceSpider-x86_64.AppImage.
3. Move it to ~/.local/bin or /opt/spacespider so it stays on your PATH.
4. Run ./SpaceSpider-x86_64.AppImage.

To integrate with your desktop environment, right-click the AppImage in your file manager and choose "Integrate with desktop", or install appimaged and drop the AppImage in ~/Applications. That gives you a Start Menu entry, a taskbar icon, and MIME associations.

Option 2: Install via .deb

On Debian and Ubuntu, use the .deb for a system-wide install with cleaner uninstall semantics.

sudo dpkg -i SpaceSpider_amd64.deb
sudo apt --fix-broken install

The first command installs the package. The second pulls any missing runtime libraries such as WebKitGTK if they were not already on the system.

Launch SpaceSpider from your application menu or from the command line:

spacespider

First launch and first space

1. Run SpaceSpider.
2. The home view appears. Click New Space.
3. Pick a project folder.
4. Give the space a short name.
5. Choose a grid size (1, 2, 3, 4, 6, 8, or 9 panes).
6. Assign a CLI to each pane.
7. Click Create.

Each pane spawns a real Unix PTY and runs the chosen command with your project folder as the working directory. Interactive prompts, signal handling, $EDITOR, and job control all work normally.

For a full walkthrough, see Create Your First Space.

Configure the shell

Shell panes default to $SHELL, which on most distros is /bin/bash. To pin a different shell for SpaceSpider without changing your login shell, set SPACESPIDER_SHELL in your profile:

export SPACESPIDER_SHELL=/usr/bin/fish

Wayland vs X11

SpaceSpider works on both display servers. Wayland sessions use the XWayland bridge if your WebKitGTK build does not yet ship native Wayland support, which is still common on LTS releases. If you see screen tearing or cursor artifacts, force X11:

GDK_BACKEND=x11 spacespider

If you prefer to let WebKitGTK use Wayland directly, set GDK_BACKEND=wayland instead. Most users do not need to override this.

Auto-updates

The AppImage and .deb both ship with the Tauri updater. On launch the app checks for signed artifacts and, if one is available, downloads the patch, verifies it against the publisher key, and swaps it in. See Updating SpaceSpider for details on the update channels.

If you manage SpaceSpider with apt via a PPA, use apt upgrade as usual instead of the in-app flow.

Uninstall

For the AppImage: just delete the file and its desktop entry under ~/.local/share/applications.

For the .deb:

sudo apt remove spacespider

Remove the config directory to wipe stored spaces:

rm -rf ~/.config/SpaceSpider

Troubleshooting Linux installs

• AppImage fails with "fuse: not found": install libfuse2 on Ubuntu or use the --appimage-extract-and-run flag.
• Blank window on launch: WebKitGTK is missing or compositor driver is misbehaving. Reinstall libwebkit2gtk-4.1-0 and relaunch.
• Panes show command not found: the target CLI is not on the PATH your desktop environment launches apps with. Start SpaceSpider from a terminal instead.
• Hardware acceleration glitches: set WEBKIT_DISABLE_COMPOSITING_MODE=1 before launch.

For more, see Troubleshooting.

Frequently asked questions

Is there a Flatpak or Snap?

Not officially. The AppImage covers most of the ground a Flatpak would. A Flatpak is under consideration.

Does it work on ARM64 Linux (Raspberry Pi, Asahi)?

An arm64 AppImage is available on a best-effort basis. The Tauri 2 runtime and WebKitGTK work, though performance on Pi 4 is limited.

Can I script SpaceSpider from a shell?

The command spacespider --space <name> opens a specific space directly. Full CLI flags are documented in the release notes.

How do I move spaces between Linux machines?

Copy ~/.config/SpaceSpider/spaces.json to the same path on the new machine before first launch.

Why does the app want libayatana-appindicator?

Tauri 2 uses it to render a system tray icon. You can skip installing it; the tray icon will simply not appear.

Related reading

• Getting Started with SpaceSpider
• Using a Plain Shell Pane in SpaceSpider
• Troubleshooting Common Issues