proxmox/docs/01-getting-started/PREREQUISITES.md

Prerequisites and Setup Requirements

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Complete list of prerequisites and setup steps for the Proxmox workspace.

System Prerequisites

Required Software

1. Node.js

   • Version: 16.0.0 or higher
   • Check: node --version
   • Install: Download from nodejs.org or use package manager

2. pnpm

   • Version: 8.0.0 or higher
   • Check: pnpm --version
   • Install: npm install -g pnpm

3. Git

   • Any recent version
   • Check: git --version
   • Install: Usually pre-installed on Linux/Mac

Optional but recommended (automation / jump host)

Useful when running scripts/push-templates-to-proxmox.sh, verification, or SSH-based automation:

• sshpass — Non-interactive SSH with password when keys are not set (optional; prefer SSH keys).
• rsync — Efficient file sync for template push (script falls back to scp if missing).
• dnsutils, iproute2 — dig, ss for DNS/socket checks.
• screen or tmux — Long-running deployment sessions.
• htop — Process monitoring.
• shellcheck — For scripts/verify/run-shellcheck.sh.
• parallel — GNU parallel for batch operations.

Install (Debian/Ubuntu): sudo apt install -y sshpass rsync dnsutils iproute2 screen tmux htop shellcheck parallel
Full list: 11-references/APT_PACKAGES_CHECKLIST.md § Automation / jump host.

Optional but recommended (deployment)

• Proxmox VE (if deploying containers)
  • Version: 7.0+ or 8.4+/9.0+
  • For local development, you can use the MCP server to connect to remote Proxmox

Workspace Prerequisites

1. Repository Setup

# Clone repository (if applicable)
git clone <repository-url>
cd proxmox

# Initialize submodules
git submodule update --init --recursive

2. Workspace Structure

Required structure:

proxmox/
├── package.json              # Root workspace config
├── pnpm-workspace.yaml       # Workspace definition
├── mcp-proxmox/              # MCP server submodule
│   ├── index.js
│   └── package.json
└── ProxmoxVE/                # Helper scripts submodule
    └── frontend/
        └── package.json

3. Dependencies Installation

# Install all workspace dependencies
pnpm install

This installs dependencies for:

• mcp-proxmox-server - MCP server packages
• proxmox-helper-scripts-website - Frontend packages

Configuration Prerequisites

1. Environment Variables (.env)

Location: /home/intlc/.env

Required variables:

PROXMOX_HOST=your-proxmox-ip-or-hostname
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=your-token-secret
PROXMOX_ALLOW_ELEVATED=false

Optional variables:

PROXMOX_PORT=8006  # Defaults to 8006

2. Claude Desktop Configuration

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

Required configuration:

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/home/intlc/projects/proxmox/mcp-proxmox/index.js"]
    }
  }
}

Proxmox Server Prerequisites (if deploying)

1. Proxmox VE Installation

• Version 7.0+ or 8.4+/9.0+
• Access to Proxmox web interface
• API access enabled

2. API Token Creation

Create API token via Proxmox UI:

1. Log into Proxmox web interface
2. Navigate to Datacenter → Permissions → API Tokens
3. Click Add to create new token
4. Save Token ID and Secret

Or use the script:

./scripts/create-proxmox-token.sh <host> <user> <password> <token-name>

3. LXC Template (for container deployments)

Download base template:

pveam download local debian-12-standard_12.2-1_amd64.tar.zst

Or use all-templates.sh script:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/tools/addon/all-templates.sh)"

Verification Steps

1. Run Complete Setup

./scripts/complete-setup.sh

This script verifies and completes:

• ✅ Prerequisites check
• ✅ Submodule initialization
• ✅ Dependency installation
• ✅ Configuration file creation
• ✅ Final verification

2. Run Verification Script

./scripts/verify-setup.sh

3. Test MCP Server

# Test basic functionality (requires .env configured)
pnpm test:basic

# Start MCP server
pnpm mcp:start

Quick Setup Checklist

• Node.js 16+ installed
• pnpm 8+ installed
• Git installed
• Repository cloned
• Submodules initialized
• Dependencies installed (pnpm install)
• .env file created and configured
• Claude Desktop config created
• (Optional) Proxmox API token created
• (Optional) LXC template downloaded
• Verification script passes

Troubleshooting Prerequisites

Node.js Issues

# Check version
node --version

# Install/update via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

pnpm Issues

# Install globally
npm install -g pnpm

# Or use corepack (Node.js 16.9+)
corepack enable
corepack prepare pnpm@latest --activate

Submodule Issues

# Force update submodules
git submodule update --init --recursive --force

# If submodules are outdated
git submodule update --remote

Dependency Issues

# Clean install
rm -rf node_modules */node_modules */*/node_modules
rm -rf pnpm-lock.yaml */pnpm-lock.yaml
pnpm install

Next Steps After Prerequisites

1. Configure Proxmox credentials in .env
2. Restart Claude Desktop (if using MCP server)
3. Test connection with pnpm test:basic
4. Start development with pnpm mcp:dev or pnpm frontend:dev