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.

<img width="1725" height="1088" alt="image" src="https://github.com/user-attachments/assets/75323765-7375-4346-a41e-08d219275248" />

🎯 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:
1. Connects to your configured PVE servers
2. Scans LXC container configurations
3. Looks for containers with community-script tags
4. 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:
1. Check for Updates: System automatically checks GitHub for new releases
2. Download Update: Downloads the latest release files
3. Backup Current Version: Creates backup of current installation
4. Install New Version: Replaces files and updates dependencies
5. Build Application: Compiles the updated code
6. Restart Server: Stops old server and starts new version
7. 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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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.