PVE Scripts Local 🚀

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. No more need for curl -> bash calls, it all happens in your enviroment.

🎯 Deployment Options

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

📦 Debian LXC Container: Deploy inside a Debian LXC container for better isolation
🔧 Helper Script: Use the automated helper 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 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

🚀 Installation

Choose the installation method that best fits your environment:

Option 1: 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)"

Step 2: Install Dependencies in Container

# 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/community-scripts/ProxmoxVE-Local.git /opt/PVESciptslocal
cd PVESciptslocal

# Install dependencies and build
npm install
cp .env.example .env
npm run build

# 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)
# Create systemd service for easy management

Access the application:

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

Option 2: Use the helper script

This creates the LXC and installs the APP for you.

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

🎯 Usage

1. Access the Web Interface

The web interface is accessible regardless of your deployment method:

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

2. Service Management

For helper-script 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 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 the ProxmoxVE 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

📖 Feature Guide

This section provides detailed information about the application's key features and how to use them effectively.

Server Settings

Manage your Proxmox VE servers and configure connection settings.

Adding PVE Servers:

Server Name: A friendly name to identify your server
IP Address: The IP address or hostname of your PVE server
Username: PVE user account (usually root or a dedicated user)
SSH Port: Default is 22, change if your server uses a different port

Authentication Types:

Password: Use username and password authentication
SSH Key: Use SSH key pair for secure authentication
Both: Try SSH key first, fallback to password if needed

Server Color Coding: Assign colors to servers for visual distinction throughout the application. This helps identify which server you're working with when managing scripts. This needs to be enabled in the General Settings.

General Settings

Configure application preferences and behavior.

Save Filters: When enabled, your script filter preferences (search terms, categories, sorting) will be automatically saved and restored when you return to the application:

Search queries are preserved
Selected script types are remembered
Sort preferences are maintained
Category selections are saved

Server Color Coding: Enable visual color coding for servers throughout the application. This makes it easier to identify which server you're working with.

GitHub Integration: Add a GitHub Personal Access Token to increase API rate limits and improve performance:

Bypasses GitHub's rate limiting for unauthenticated requests
Improves script loading and syncing performance
Token is stored securely and only used for API calls

Authentication: Secure your application with username and password authentication:

Set up username and password for app access
Enable/disable authentication as needed
Credentials are stored securely

Sync Button

Synchronize script metadata from the ProxmoxVE GitHub repository.

What Does Syncing Do?

Updates Script Metadata: Downloads the latest script information (JSON files)
Refreshes Available Scripts: Updates the list of scripts you can download
Updates Categories: Refreshes script categories and organization
Checks for Updates: Identifies which downloaded scripts have newer versions

Important Notes:

Metadata Only: Syncing only updates script information, not the actual script files
No Downloads: Script files are downloaded separately when you choose to install them
Last Sync Time: Shows when the last successful sync occurred
Rate Limits: GitHub API limits may apply without a personal access token

When to Sync:

When you want to see the latest available scripts
To check for updates to your downloaded scripts
If you notice scripts are missing or outdated
After the ProxmoxVE repository has been updated

Available Scripts

Browse and discover scripts from the ProxmoxVE repository.

Browsing Scripts:

Category Sidebar: Filter scripts by category (Storage, Network, Security, etc.)
Search: Find scripts by name or description
View Modes: Switch between card and list view
Sorting: Sort by name or creation date

Filtering Options:

Script Types: Filter by CT (Container) or other script types
Update Status: Show only scripts with available updates
Search Query: Search within script names and descriptions
Categories: Filter by specific script categories

Script Actions:

View Details: Click on a script to see full information and documentation
Download: Download script files to your local system
Install: Run scripts directly on your PVE servers
Preview: View script content before downloading

Downloaded Scripts

Manage scripts that have been downloaded to your local system.

What Are Downloaded Scripts? These are scripts that you've downloaded from the repository and are stored locally on your system:

Script files are stored in your local scripts directory
You can run these scripts on your PVE servers
Scripts can be updated when newer versions are available

Update Detection: The system automatically checks if newer versions of your downloaded scripts are available:

Scripts with updates available are marked with an update indicator
You can filter to show only scripts with available updates
Update detection happens when you sync with the repository

Managing Downloaded Scripts:

Update Scripts: Download the latest version of a script
View Details: See script information and documentation
Install/Run: Execute scripts on your PVE servers
Filter & Search: Use the same filtering options as Available Scripts

Installed Scripts

Track and manage scripts that are installed on your PVE servers.

Auto-Detection (Primary Feature): The system can automatically detect LXC containers that have community-script tags on your PVE servers:

Automatic Discovery: Scans your PVE servers for containers with community-script tags
Container Detection: Identifies LXC containers running Proxmox helper scripts
Server Association: Links detected scripts to the specific PVE server
Bulk Import: Automatically creates records for all detected scripts

How Auto-Detection Works:

Connects to your configured PVE servers
Scans LXC container configurations
Looks for containers with community-script tags
Creates installed script records automatically

Manual Script Management:

Add Scripts Manually: Create records for scripts not auto-detected
Edit Script Details: Update script names and container IDs
Delete Scripts: Remove scripts from tracking
Bulk Operations: Clean up old or invalid script records

Script Tracking Features:

Installation Status: Track success, failure, or in-progress installations
Server Association: Know which server each script is installed on
Container ID: Link scripts to specific LXC containers
Web UI Access: Track and access Web UI IP addresses and ports
Execution Logs: View output and logs from script installations
Filtering: Filter by server, status, or search terms

Managing Installed Scripts:

View All Scripts: See all tracked scripts across all servers
Filter by Server: Show scripts for a specific PVE server
Filter by Status: Show successful, failed, or in-progress installations
Sort Options: Sort by name, container ID, server, status, or date
Update Scripts: Re-run or update existing script installations

Web UI Access: Automatically detect and access Web UI interfaces for your installed scripts:

Auto-Detection: Automatically detects Web UI URLs from script installation output
IP & Port Tracking: Stores and displays Web UI IP addresses and ports
One-Click Access: Click IP:port to open Web UI in new tab
Manual Detection: Re-detect IP using hostname -I inside container
Port Detection: Uses script metadata to get correct port (e.g., actualbudget:5006)
Editable Fields: Manually edit IP and port values as needed

Actions Dropdown: Clean interface with all actions organized in a dropdown menu:

Edit Button: Always visible for quick script editing
Actions Dropdown: Contains Update, Shell, Open UI, Start/Stop, Destroy, Delete
Smart Visibility: Dropdown only appears when actions are available
Auto-Close: Dropdown closes after clicking any action
Disabled States: Actions are disabled when container is stopped

Container Control: Directly control LXC containers from the installed scripts page via SSH:

Start/Stop Button: Control container state with pct start/stop <ID>
Container Status: Real-time status indicator (running/stopped/unknown)
Destroy Button: Permanently remove LXC container with pct destroy <ID>
Confirmation Modals: Simple OK/Cancel for start/stop, type container ID to confirm destroy
SSH Execution: All commands executed remotely via configured SSH connections

Safety Features:

Start/Stop actions require simple confirmation
Destroy action requires typing the container ID to confirm
All actions show loading states and error handling
Only works with SSH scripts that have valid container IDs

Update System

Keep your PVE Scripts Management application up to date with the latest features and improvements.

What Does Updating Do?

Downloads Latest Version: Fetches the newest release from the GitHub repository
Updates Application Files: Replaces current files with the latest version
Installs Dependencies: Updates Node.js packages and dependencies
Rebuilds Application: Compiles the application with latest changes
Restarts Server: Automatically restarts the application server

How to Update:

Automatic Update (Recommended):

Click the "Update Now" button when an update is available
The system will handle everything automatically
You'll see a progress overlay with update logs
The page will reload automatically when complete

Manual Update (Advanced): If automatic update fails, you can update manually:

# Navigate to the application directory
cd $PVESCRIPTLOCAL_DIR

# Pull latest changes
git pull

# Install dependencies
npm install

# Build the application
npm run build

# Start the application
npm start

Update Process:

Check for Updates: System automatically checks GitHub for new releases
Download Update: Downloads the latest release files
Backup Current Version: Creates backup of current installation
Install New Version: Replaces files and updates dependencies
Build Application: Compiles the updated code
Restart Server: Stops old server and starts new version
Reload Page: Automatically refreshes the browser

Release Notes: Click the external link icon next to the update button to view detailed release notes on GitHub:

See what's new in each version
Read about bug fixes and improvements
Check for any breaking changes
View installation requirements

Important Notes:

Backup: Your data and settings are preserved during updates
Downtime: Brief downtime occurs during the update process
Compatibility: Updates maintain backward compatibility with your data
Rollback: If issues occur, you can manually revert to previous version

📁 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.

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

Name		Name	Last commit message	Last commit date
Latest commit History 190 Commits
.github		.github
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
VERSION		VERSION
eslint.config.js		eslint.config.js
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
prettier.config.js		prettier.config.js
server.js		server.js
tsconfig.json		tsconfig.json
update.sh		update.sh
vitest.config.ts		vitest.config.ts

community-scripts/ProxmoxVE-Local

Folders and files

Latest commit

History

Repository files navigation