A modern web-based management interface for Proxmox VE (PVE) helper scripts. This tool provides a user-friendly way to discover, download, and execute community-sourced Proxmox scripts locally with real-time terminal output streaming.

🎯 Deployment Options

This application can be deployed in multiple ways to suit different environments:

🐧 Proxmox Host: Run directly on your Proxmox VE host system
📦 Debian LXC Container: Deploy inside a Debian LXC container for better isolation
⚡ Quick Install: Use the automated install.sh script for easy setup

All deployment methods provide the same functionality and web interface.

🌟 Features

Web-based Interface: Modern React/Next.js frontend with real-time terminal emulation
Script Discovery: Browse and search through community Proxmox scripts from GitHub
One-Click Execution: Run scripts directly from the web interface with live output
Real-time Terminal: Full terminal emulation with xterm.js for interactive script execution
Script Management: Download, update, and manage local script collections
Security: Sandboxed script execution with path validation and time limits
Database Integration: PostgreSQL backend for script metadata and execution history
WebSocket Communication: Real-time bidirectional communication for script execution

🏗️ Architecture

Frontend

Next.js 15 with React 19
TypeScript for type safety
Tailwind CSS for styling
xterm.js for terminal emulation
tRPC for type-safe API communication

Backend

Node.js server with WebSocket support
WebSocket Server for real-time script execution
Script Downloader Service for GitHub integration

Scripts

Core Functions: Shared utilities and build functions
Container Scripts: Pre-configured LXC container setups
Installation Scripts: System setup and configuration tools

Database

SQLite Database: Local database stored at data/settings.db
Server Management: Stores Proxmox server configurations and credentials
Automatic Setup: Database and tables are created automatically on first run
Data Persistence: Settings persist across application restarts

📋 Prerequisites

For All Deployment Methods

Node.js 22+ and npm
Git for cloning the repository
Proxmox VE environment (host or access to Proxmox cluster)
SQLite (included with Node.js better-sqlite3 package)

For Proxmox Host Installation

build-essentials: apt install build-essential
Direct access to Proxmox host system

For Debian LXC Container Installation

Debian LXC container (Debian 11+ recommended)
build-essentials: apt install build-essential
Container with sufficient resources (2GB RAM, 4GB storage minimum)
Network access from container to Proxmox host
Optional: Privileged container for full Proxmox integration

For Quick Install (install.sh)

Proxmox VE host (script automatically detects and configures)
Internet connectivity for downloading dependencies

🚀 Installation

Choose the installation method that best fits your environment:

Option 1: Quick Install with install.sh (Recommended for Proxmox Host)

Run this command directly on your Proxmox VE host or on any Debian based lxc:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/michelroegl-brunner/PVESciptslocal/main/install.sh)"

What the script does:

✅ Installs required dependencies (build-essential, git, Node.js 24.x)
✅ Clones the repository into /opt/PVESciptslocal (or your chosen path)
✅ Runs npm install and builds the project
✅ Sets up .env from .env.example if missing
✅ Creates database directory (data/) for SQLite storage
✅ Creates a systemd service (pvescriptslocal.service) for easy management

After installation:

🌐 Access the app at: http://<YOUR_PVE_OR_LXC_IP>:3000

🔧 Manage the service with:

systemctl start pvescriptslocal
systemctl stop pvescriptslocal
systemctl status pvescriptslocal

Option 2: Debian LXC Container Installation

For better isolation and security, you can run PVE Scripts Local inside a Debian LXC container:

Step 1: Create Debian LXC Container

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"

Then run the installer:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/michelroegl-brunner/PVESciptslocal/main/install.sh)"

Step 2: Install Dependencies in Container when installer is not used

# Enter the container
pct enter 100

# Update and install dependencies
apt update && apt install -y build-essential git curl

# Install Node.js 24.x
curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
apt install -y nodejs

Step 3: Clone and Setup Application

# Clone the repository
git clone https://github.com/michelroegl-brunner/PVESciptslocal.git /opt/PVESciptslocal
cd /opt/PVESciptslocal

# Install dependencies and build
npm install
npm run build

# Setup environment
cp .env.example .env

# Create database directory
mkdir -p data
chmod 755 data

Step 4: Start the Application

# Start in production mode
npm start

# Or create a systemd service (optional)
# Follow the same systemd setup as the install.sh script

Access the application:

🌐 Container IP: http://<CONTAINER_IP>:3000
🔧 Container management: pct start 100, pct stop 100, pct status 100

Option 3: Manual Installation (Proxmox Host)

Step 1: Clone the Repository

git clone https://github.com/michelroegl-brunner/PVESciptslocal.git
cd PVESciptslocal

Step 2: Install Dependencies

npm install

Step 3: Environment Configuration

cp .env.example .env
# Edit .env file with your specific settings if needed

Step 4: Database Setup

# Create database directory
mkdir -p data
chmod 755 data

Step 5: Build and Start

# Production mode
npm run build
npm start

# Development mode
npm run dev:server

Access the application:

🌐 Available at: http://<YOUR_IP>:3000

📝 LXC Container Specific Notes

Container Requirements

OS: Debian 11+ (Debian 12 recommended)
Resources: Minimum 2GB RAM, 4GB storage
Network: Bridge connection to Proxmox network
Privileges: Unprivileged containers work, but privileged containers provide better Proxmox integration

Container Configuration Tips

Privileged Container: Use --unprivileged 0 for full Proxmox API access
Resource Allocation: Allocate at least 2 CPU cores and 2GB RAM for optimal performance
Storage: Use at least 8GB for the container to accommodate Node.js and dependencies
Network: Ensure the container can reach the Proxmox host API

Security Considerations

Unprivileged Containers: More secure but may have limited Proxmox functionality
Privileged Containers: Full Proxmox access but less secure isolation
Network Access: Ensure proper firewall rules for the container

Troubleshooting LXC Installation

Permission Issues: Ensure the container has proper permissions for Proxmox API access
Network Connectivity: Verify the container can reach the Proxmox host
Resource Limits: Check if the container has sufficient resources allocated

🎯 Usage

1. Access the Web Interface

The web interface is accessible regardless of your deployment method:

Proxmox Host Installation: http://<PROXMOX_HOST_IP>:3000
LXC Container Installation: http://<CONTAINER_IP>:3000
Custom Installation: http://<YOUR_IP>:3000

2. Service Management

For install.sh installations (systemd service):

# Start the service
systemctl start pvescriptslocal

# Stop the service
systemctl stop pvescriptslocal

# Check service status
systemctl status pvescriptslocal

# Enable auto-start on boot
systemctl enable pvescriptslocal

# View service logs
journalctl -u pvescriptslocal -f

For LXC container installations:

# Container management
pct start <container_id>    # Start container
pct stop <container_id>     # Stop container
pct status <container_id>   # Check container status

# Access container shell
pct enter <container_id>

# Inside container - start application
cd /opt/PVESciptslocal
npm start

For manual installations:

# Start application
npm start

# Development mode
npm run dev:server

# Build for production
npm run build

3. Browse Available Scripts

The main page displays a grid of available Proxmox scripts
Use the search functionality to find specific scripts
Scripts are categorized by type (containers, installations, etc.)

4. Download Scripts

Click on any script card to view details
Use the "Download" button to fetch scripts from GitHub
Downloaded scripts are stored locally in the scripts/ directory

5. Execute Scripts

Click "Run Script" on any downloaded script
A terminal window will open with real-time output
Interact with the script through the web terminal
Use the close button to stop execution

6. Script Management

View script execution history
Update scripts to latest versions
Manage local script collections

7. Database Management

The application uses SQLite for storing server configurations:

Database Location: data/settings.db
Automatic Creation: Database and tables are created on first run
Server Storage: Proxmox server credentials and configurations
Backup: Copy data/settings.db to backup your server configurations
Reset: Delete data/settings.db to reset all server configurations

📁 Project Structure

PVESciptslocal/
├── scripts/                  # Script collection
│   ├── core/                 # Core utility functions
│   │   ├── build.func        # Build system functions
│   │   ├── tools.func        # Tool installation functions
│   │   └── create_lxc.sh     # LXC container creation
│   ├── ct/                   # Container templates 
│   └── install/              # Installation scripts
├── src/                      # Source code
│   ├── app/                  # Next.js app directory
│   │   ├── _components/      # React components
│   │   └── page.tsx          # Main page
│   └── server/               # Server-side code
│       ├── database.js       # SQLite database service
│       └── services/         # Business logic services
├── data/                     # Database storage
│   └── settings.db           # SQLite database file
├── public/                   # Static assets
├── server.js                 # Main server file
└── package.json              # Dependencies and scripts

🚀 Development

Prerequisites for Development

Node.js 22+
Git

Development Commands

# Install dependencies
npm install

Start development server

npm run dev:server

Project Structure for Developers

Frontend: React components in src/app/_components/
Backend: Server logic in src/server/
API: tRPC routers for type-safe API communication
Scripts: Bash scripts in scripts/ directory

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Logs

Server logs: Check console output or server.log
Script execution: View in web terminal

🎯 Quick Start Summary

Choose your preferred deployment method:

Method	Best For	Command
Quick Install	Proxmox hosts or Debian LXC, easy setup	`bash -c "$(curl -fsSL https://raw.githubusercontent.com/michelroegl-brunner/PVESciptslocal/main/install.sh)"`
LXC Container	Better isolation, security	Create Debian LXC → Install dependencies → Clone repo → `npm start`
Manual Install	Custom setups, development	`git clone` → `npm install` → `npm run build` → `npm start`

All methods provide the same web interface at http://<IP>:3000 with full Proxmox script management capabilities.

Note: This is alpha software. Use with caution in production environments and always backup your Proxmox configuration before running scripts.