Bootspring
HomeGet Started

Linux Setup Guide

Complete guide to installing and configuring Bootspring on Linux distributions.

System Requirements#

RequirementMinimumRecommended
Kernel4.4+5.15+
glibc2.17+2.31+
Memory2 GB RAM8 GB RAM
Disk500 MB1 GB
Node.jsv18.0.0v20.x LTS

Supported Distributions#

DistributionVersionsStatus
Ubuntu20.04, 22.04, 24.04Full support
Debian11, 12Full support
Fedora38, 39, 40Full support
CentOS/RHEL8, 9Full support
Arch LinuxRollingFull support
openSUSELeap 15, TumbleweedFull support
Alpine3.18+Supported

Installation by Distribution#

Ubuntu / Debian#

1# Add NodeSource repository 2curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - 3 4# Install Node.js 5sudo apt-get install -y nodejs 6 7# Install Bootspring 8npm install -g bootspring 9 10# Verify 11bootspring --version

Fedora#

# Install Node.js sudo dnf install nodejs # Install Bootspring npm install -g bootspring

CentOS / RHEL 8+#

1# Enable Node.js module 2sudo dnf module enable nodejs:20 3 4# Install Node.js 5sudo dnf install nodejs 6 7# Install Bootspring 8npm install -g bootspring

Arch Linux#

# Install Node.js sudo pacman -S nodejs npm # Install Bootspring npm install -g bootspring

openSUSE#

# Install Node.js sudo zypper install nodejs20 # Install Bootspring npm install -g bootspring

Alpine Linux#

# Install Node.js apk add nodejs npm # Install Bootspring npm install -g bootspring

Universal Method: nvm (Recommended)#

Works on all distributions:

1# Install nvm 2curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash 3 4# Reload shell 5source ~/.bashrc # or ~/.zshrc 6 7# Install Node.js LTS 8nvm install --lts 9nvm use --lts 10 11# Install Bootspring 12npm install -g bootspring 13 14# Verify 15bootspring --version

Shell Configuration#

Bash#

Add to ~/.bashrc:

1# Bootspring completions 2if command -v bootspring &> /dev/null; then 3 eval "$(bootspring completions bash)" 4fi 5 6# Aliases 7alias bs="bootspring" 8alias bsg="bootspring generate" 9alias bsa="bootspring agent invoke" 10alias bss="bootspring status"

Apply:

source ~/.bashrc

Zsh#

Add to ~/.zshrc:

1# Bootspring completions 2if command -v bootspring &> /dev/null; then 3 eval "$(bootspring completions zsh)" 4fi 5 6# Aliases 7alias bs="bootspring" 8alias bsg="bootspring generate" 9alias bsa="bootspring agent invoke"

Apply:

source ~/.zshrc

Fish#

Add to ~/.config/fish/config.fish:

1# Bootspring completions 2if command -v bootspring &> /dev/null 3 bootspring completions fish | source 4end 5 6# Aliases 7alias bs="bootspring" 8alias bsg="bootspring generate"

Apply:

source ~/.config/fish/config.fish

Authentication#

Browser Login#

bootspring login

Opens your default browser. If no display:

# Device code flow bootspring login --device

Environment Variable#

1# Current session 2export BOOTSPRING_API_KEY="bs_live_xxx" 3 4# Permanent 5echo 'export BOOTSPRING_API_KEY="bs_live_xxx"' >> ~/.bashrc 6source ~/.bashrc

Secure Storage with pass#

1# Install pass 2sudo apt install pass # Debian/Ubuntu 3sudo dnf install pass # Fedora 4 5# Initialize GPG key 6gpg --gen-key 7 8# Initialize pass 9pass init <gpg-key-id> 10 11# Store API key 12pass insert bootspring/api-key 13 14# Use in shell config 15export BOOTSPRING_API_KEY=$(pass bootspring/api-key)

Using secret-tool (GNOME)#

# Store secret-tool store --label="Bootspring API Key" service bootspring key api-key <<< "bs_live_xxx" # Retrieve export BOOTSPRING_API_KEY=$(secret-tool lookup service bootspring key api-key)

Project Setup#

Initialize Project#

cd ~/projects/my-app bootspring init

Configure for Project Type#

# Interactive mode bootspring init --interactive # Auto-detect bootspring init --yes

VS Code Integration#

Install VS Code#

Ubuntu/Debian:

wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg sudo install -D -o root -g root -m 644 packages.microsoft.gpg /etc/apt/keyrings/packages.microsoft.gpg sudo sh -c 'echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list' sudo apt update sudo apt install code

Fedora:

sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc sudo sh -c 'echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com/yumrepos/vscode\nenabled=1\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" > /etc/yum.repos.d/vscode.repo' sudo dnf install code

Arch:

yay -S visual-studio-code-bin

Install Bootspring Extension#

code --install-extension bootspring.bootspring-vscode

Claude Desktop Integration#

Install Claude Desktop#

Ubuntu/Debian (AppImage):

1# Download AppImage 2wget https://claude.ai/download/linux -O claude-desktop.AppImage 3chmod +x claude-desktop.AppImage 4 5# Run 6./claude-desktop.AppImage

Snap (if available):

snap install claude-desktop

Flatpak (if available):

flatpak install flathub com.anthropic.claude

Configure MCP Server#

bootspring mcp install

Manual Configuration#

Edit ~/.config/Claude/claude_desktop_config.json:

1{ 2 "mcpServers": { 3 "bootspring": { 4 "command": "npx", 5 "args": ["-y", "bootspring", "mcp", "serve"], 6 "env": { 7 "BOOTSPRING_API_KEY": "your-api-key" 8 } 9 } 10 } 11}

AppImage MCP Path#

If using AppImage, you may need to specify the full path:

1{ 2 "mcpServers": { 3 "bootspring": { 4 "command": "/home/user/.nvm/versions/node/v20.10.0/bin/npx", 5 "args": ["-y", "bootspring", "mcp", "serve"] 6 } 7 } 8}

Terminal Emulators#

GNOME Terminal#

Default on Ubuntu, Fedora GNOME. Works out of the box.

Alacritty#

1# Install 2sudo apt install alacritty # or your package manager 3 4# Config (~/.config/alacritty/alacritty.toml) 5[shell] 6program = "/bin/zsh" 7args = ["-l"]

Kitty#

# Install sudo apt install kitty # Works out of the box with completions

Tilix#

sudo apt install tilix

Terminator#

sudo apt install terminator

JetBrains IDE Setup#

Install Toolbox#

wget https://download.jetbrains.com/toolbox/jetbrains-toolbox-2.1.3.18901.tar.gz tar -xzf jetbrains-toolbox-*.tar.gz ./jetbrains-toolbox-*/jetbrains-toolbox

Configure Terminal#

Settings → Tools → Terminal:

  • Shell path: /bin/zsh or /bin/bash

Install Plugin#

  1. Settings (Ctrl+Alt+S)
  2. Plugins → Marketplace
  3. Search "Bootspring"
  4. Install

Neovim Integration#

Install Neovim#

1# Ubuntu/Debian 2sudo apt install neovim 3 4# Fedora 5sudo dnf install neovim 6 7# Arch 8sudo pacman -S neovim

Configure for Bootspring#

Add to ~/.config/nvim/init.lua:

1-- Bootspring commands 2vim.api.nvim_create_user_command('BootspringGenerate', function() 3 vim.fn.system('bootspring generate') 4 print('Context regenerated') 5end, {}) 6 7vim.api.nvim_create_user_command('BootspringAgent', function(opts) 8 local result = vim.fn.system('bootspring agent invoke ' .. opts.args) 9 print(result) 10end, { nargs = '+' }) 11 12-- Keymaps 13vim.keymap.set('n', '<leader>bg', ':BootspringGenerate<CR>') 14vim.keymap.set('n', '<leader>ba', ':BootspringAgent ')

systemd Integration#

User Service#

Create ~/.config/systemd/user/bootspring-mcp.service:

1[Unit] 2Description=Bootspring MCP Server 3After=network.target 4 5[Service] 6Type=simple 7ExecStart=/usr/bin/npx bootspring mcp serve 8Restart=on-failure 9Environment=BOOTSPRING_API_KEY=bs_live_xxx 10 11[Install] 12WantedBy=default.target

Enable:

systemctl --user enable bootspring-mcp systemctl --user start bootspring-mcp

npm Permission Issues#

Option 1: nvm (Recommended)#

Using nvm avoids all permission issues:

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

Option 2: Change npm Directory#

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

Option 3: Fix Permissions (Not Recommended)#

sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

Firewall Configuration#

UFW (Ubuntu)#

# Allow outbound HTTPS (for API) sudo ufw allow out 443/tcp

firewalld (Fedora/RHEL)#

# Usually allowed by default sudo firewall-cmd --list-all

Troubleshooting#

Command Not Found#

1# Check if npm bin is in PATH 2echo $PATH | grep -E "(npm|node)" 3 4# Find npm global bin 5npm bin -g 6 7# Add to PATH 8export PATH="$(npm bin -g):$PATH" 9echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.bashrc

Permission Denied#

# Use nvm to avoid permission issues curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install --lts npm install -g bootspring

GLIBC Version Error#

# Check glibc version ldd --version # May need to use newer distribution or container

SSL Certificate Errors#

1# Update CA certificates 2sudo apt install ca-certificates 3sudo update-ca-certificates 4 5# Or for Node.js specifically 6npm config set cafile /etc/ssl/certs/ca-certificates.crt

Display Not Found (Browser Login)#

1# Use device code flow instead 2bootspring login --device 3 4# Or set browser manually 5export BROWSER=/usr/bin/firefox 6bootspring login

AppArmor/SELinux Blocking#

AppArmor (Ubuntu):

sudo aa-complain /usr/bin/node

SELinux (Fedora/RHEL):

# Check denials sudo ausearch -m avc -ts recent # Temporary permissive sudo setenforce 0

Health Check#

bootspring doctor

Expected output:

Bootspring Health Check ======================= System: ✓ Ubuntu 22.04.3 LTS ✓ Intel Core i7-12700K ✓ 32 GB RAM Runtime: ✓ Node.js v20.10.0 (x64) ✓ npm v10.2.3 ✓ Bootspring v1.2.0 Configuration: ✓ Config file: Valid ✓ Context file: Present ✓ API key: Configured Network: ✓ API: Connected ✓ Latency: 38ms Integrations: ✓ VS Code: Extension installed All 11 checks passed!

Docker Usage#

Run in Container#

1FROM node:20-alpine 2 3RUN npm install -g bootspring 4 5WORKDIR /app 6COPY . . 7 8RUN bootspring generate 9 10CMD ["bootspring", "mcp", "serve"]

Docker Compose#

1version: '3.8' 2services: 3 bootspring: 4 image: node:20-alpine 5 command: npx bootspring mcp serve 6 environment: 7 - BOOTSPRING_API_KEY=${BOOTSPRING_API_KEY} 8 volumes: 9 - ./:/app 10 working_dir: /app

Uninstallation#

Remove Bootspring#

npm uninstall -g bootspring

Clean Configuration#

rm -rf ~/.bootspring rm -rf ~/.config/bootspring

Remove Shell Completions#

Edit ~/.bashrc or ~/.zshrc and remove Bootspring lines.

Next Steps#