A Terminal User Interface For Proxmox Virtual Environment

Features • Screenshots • Installation • Configuration • Usage • Theming • VNC Console

• Lightning Fast: Intelligent caching for responsive performance
• Complete Management: VMs, containers, nodes, and cluster resources
• Multi-Profile Support: Manage multiple Proxmox connections with profile switching
• Automatic Migration: Legacy configs seamlessly migrate to modern profile-based format
• Secure Authentication: API tokens or password-based auth with automatic renewal
• Integrated Shells: SSH directly to nodes, VMs, and containers
• VNC Console Access: Embedded noVNC client with automatic authentication
• Plugin System: Opt-in extensions including the Community Scripts installer; enable via Manage Plugins dialog or config file
• Modern Interface: Vim-style navigation with customizable key bindings
• Flexible Theming: Automatic adaptation to terminal emulator color schemes
• Comprehensive Documentation: Detailed guides for configuration, theming, and development

Node Management - Real-time cluster monitoring and control

Guest Management - VM and container operations

📸 See docs/SCREENSHOTS.md for a complete showcase of all available screenshots and interface features

Recommended for Go users: pvetui now supports one-command install using Go modules!

go install github.com/devnullvoid/pvetui/cmd/pvetui@latest

From Pre-compiled Binaries:

1. Download from Releases
2. Extract and run: ./pvetui

macOS Users: You may encounter Gatekeeper warnings with pre-compiled binaries. See Troubleshooting Guide for solutions including bypassing the warning or building from source.

Arch Linux (AUR):

# Binary package (recommended)
yay -S pvetui-bin

# OR build from source
yay -S pvetui-git

macOS (Homebrew):

# Add the tap repository
brew tap devnullvoid/pvetui

# Install pvetui
brew install pvetui

Windows (Scoop):

# Add the bucket
scoop bucket add pvetui https://github.com/devnullvoid/scoop-pvetui

# Install pvetui
scoop install pvetui

From Source:

git clone https://github.com/devnullvoid/pvetui.git
cd pvetui
make install  # Build and install from source
# or: make install-go  # Install via Go toolchain

• On first run, the app will offer to create and edit a config file in a user-friendly TUI wizard
• Launch the wizard anytime with --config-wizard
• Create and manage multiple connection profiles with validation
• Edit, validate, and save your config (supports SOPS-encrypted files)
• Only one authentication method (password or token) per profile is allowed
• All errors and confirmations are shown in clear, interactive modals

pvetui uses a modern multi-profile configuration format that supports multiple Proxmox connections:

profiles:
  default:
    addr: "https://your-proxmox-host:8006"
    user: "your-user"
    realm: "pam"
    # Choose one authentication method:
    password: "your-password"           # Method 1: Password auth
    # OR
    token_id: "your-token-id"          # Method 2: API token (recommended)
    token_secret: "your-secret"
    insecure: false
    ssh_user: "your-ssh-user"

  work:
    addr: "https://work-proxmox:8006"
    user: "workuser"
    token_id: "worktoken"
    token_secret: "worksecret"
    realm: "pam"
    insecure: false
    ssh_user: "workuser"

default_profile: "default"
debug: false

pvetui includes an opt-in plugin system for optional features. Plugins are disabled by default and must be explicitly enabled.

• community-scripts: Adds the popular Community Scripts installer to node context menus
• demo-guest-list: Example plugin showing running guests (for reference/testing)

Method 1: Manage Plugins Dialog (Recommended)

1. Press g to open the Global Menu
2. Select Manage Plugins
3. Use arrow keys or j/k to navigate the plugin list
4. Press Space to toggle plugins on/off
5. Press Enter to save changes
6. Restart pvetui for changes to take effect

Method 2: Configuration File

Add plugin IDs to your config file:

plugins:
  enabled:
    - "community-scripts"
    - "demo-guest-list"

📖 For plugin development and advanced details, see docs/PLUGINS.md

The built-in profile manager allows you to:

• Switch between profiles (e.g., home, work, development)
• Add new profiles with different Proxmox connections
• Edit existing profiles with validation
• Delete profiles with confirmation
• Set default profile for automatic connection

Access the profile manager through the global menu.

1. In Proxmox web interface: Datacenter → Permissions → API Tokens
2. Click Add → Set user (e.g., root) → Enter token ID
3. Copy the generated Token ID and Secret to your config

Note: Proxmox displays the Token ID in the form user@realm!tokenid (for example: root@pam!mytoken). When configuring pvetui, split those parts into separate fields:

profiles:
  default:
    addr: "https://your-proxmox-host:8006"
    user: "root"          # from user@realm!tokenid → user
    realm: "pam"          # from user@realm!tokenid → realm
    token_id: "mytoken"   # from user@realm!tokenid → tokenid
    token_secret: "YOUR_SECRET"

Supports SOPS encrypted config files. Point to an encrypted YAML file with --config and it will decrypt automatically.

📖 For detailed configuration options, key bindings, theming, and advanced features, see docs/CONFIGURATION.md

📚 Complete documentation is available in the docs/ folder

# Auto-detects config at ~/.config/pvetui/config.yml
./pvetui

# Or specify custom config
./pvetui --config /path/to/config.yml

Environment Variables: All flags can also be set via environment variables with PVETUI_ prefix (e.g., PVETUI_ADDR, PVETUI_USER).

Customize keys via the key_bindings section in your config. See docs/CONFIGURATION.md#key-bindings for all options (including macOS Opt key support).

pvetui supports semantic theming with automatic adaptation to your terminal's color scheme.

📖 For detailed theming options, built-in themes, and color customization, see docs/CONFIGURATION.md#theming and docs/THEMING.md

Built-in noVNC client provides seamless console access:

• Zero Configuration: Works out of the box
• Automatic Authentication: No separate login required
• Universal Support: VMs, containers, and node shells
• Secure Proxy: Local WebSocket proxy handles connections

Note: Node VNC shells require password authentication (Proxmox limitation).

Important: VNC ports must be opened and accessible on the connected Proxmox server. The TUI creates a local WebSocket proxy that connects to the Proxmox VNC endpoint, so ensure your Proxmox server's VNC ports are properly configured and accessible from your client machine.

• Access to Proxmox VE cluster
• SSH access for shell functionality
• Go 1.24+ (for building from source)

• Use SSH keys for authentication: For best security and convenience, set up SSH key-based authentication with your Proxmox hosts. Avoid password-based SSH logins.
• Passwordless pct access: Add a sudoers rule on your Proxmox hosts to allow your user to run pct enter and pct exec without being prompted for a password. Example sudoers line:

  youruser ALL=(ALL) NOPASSWD: /usr/sbin/pct enter *, /usr/sbin/pct exec *
  

Check our Troubleshooting Guide for solutions to common problems including:

• 🍎 macOS Gatekeeper warnings (zsh: killed errors)
• 🪟 Windows SmartScreen and antivirus issues
• 🐧 Linux permission problems
• 🔧 General installation and configuration issues

git clone https://github.com/devnullvoid/pvetui.git
cd pvetui
cp .env.example .env  # Edit with your Proxmox details
docker compose run --rm pvetui

See docs/DOCKER.md for advanced usage.

Contributions welcome! Check the issues page.

MIT License - see LICENSE file for details.

Proxmox® is a registered trademark of Proxmox Server Solutions GmbH in the EU, the U.S., and other countries. This project is not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH. "Proxmox" is used solely to describe compatibility with Proxmox Virtual Environment software.

This repository includes the noVNC HTML/JS client under internal/vnc/novnc via git subtree. To upgrade to a newer noVNC version, run:

git subtree pull --prefix=internal/vnc/novnc https://github.com/novnc/noVNC.git <tag-or-commit> --squash

Replace <tag-or-commit> with the desired version. After updating, prune unnecessary files if you only need the built assets. Commit the results to share the update with all users.