pvetui

A Terminal User Interface For Proxmox Virtual Environment

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

https://github.com/user-attachments/assets/c8e1183a-7204-47ac-9a15-e39ba8e275ef

🚀 Features

• 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
• Group Mode (multi-cluster): Combine multiple Proxmox profiles into one unified view with routed actions per cluster

📸 Screenshots

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

📦 Installation

Quick Start

Install via Go (Go 1.24+)

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.

Package Managers

Arch Linux (AUR):

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

# Build release package from source
yay -S pvetui

# OR build from source
yay -S pvetui-git

macOS (Homebrew Cask):

# Install directly from the tap (brew will auto-clone devnullvoid/homebrew-pvetui)
brew install --cask devnullvoid/pvetui/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

🔧 Configuration

First Run & Interactive Config Wizard

• 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

Configuration Format

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"
    vm_ssh_user: "vm-login-user"   # Optional: overrides ssh_user for QEMU VM shells
    ssh_jump_host:                 # Optional: configure a bastion host for SSH
      addr: "jump.example.com"
      user: "jumpuser"
      keyfile: "/path/to/jump.key"
      port: 2222
    groups:
      - all-servers

  work:
    addr: "https://work-proxmox:8006"
    user: "workuser"
    token_id: "worktoken"
    token_secret: "worksecret"
    realm: "pam"
    insecure: false
    ssh_user: "workuser"
    vm_ssh_user: "work-vm-user"
    ssh_jump_host:
      addr: "work-jump.example.com"
      port: 2222
    groups:
      - all-servers

default_profile: "all-servers" # Can be a profile name or a group name
debug: false
show_icons: true

vm_ssh_user is optional; when omitted, pvetui reuses ssh_user. Set it if your Proxmox host SSH account differs from the accounts you use to log into QEMU guests so VM shells work without duplicating profiles. ssh_jump_host is optional and lets you route SSH connections through a bastion host when your Proxmox nodes or VMs are not directly reachable.

Guest tags can be edited from the VM/LXC Edit Configuration form using a semicolon-separated list (for example: prod;monitoring;db).

Plugins

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

Built-in Plugins

• community-scripts: Adds the popular Community Scripts installer to node context menus
• command-runner: Execute whitelisted commands on Proxmox hosts via SSH (requires SSH key setup)
• guest-insights (legacy alias: demo-guest-list): Full guest insights modal (filter/sort/jump-to-guest)

Enabling Plugins

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"
    - "command-runner"
    - "guest-insights"     # Guest Insights plugin (legacy alias: demo-guest-list)

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

Profile Management

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.

Group Mode (multi-cluster)

Combine several profiles into a named group to see a unified cluster view (CPU/mem/storage/tasks/guests). Actions are routed to each guest’s source profile/cluster; migration targets are limited to the VM’s own cluster.

Launch directly into a group:

pvetui --profile="my-group"

Notes:

• Group names must not conflict with profile names (validation enforced).
• Refreshes fetch fresh data from all member profiles; pending states are tracked per source profile.
• Migrations stay within the VM’s original cluster; groups of standalone nodes will show “No other online nodes available.”

API Token Setup (Recommended)

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"

Encrypted Configuration

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

Not using SOPS yet? pvetui now auto-detects cleartext password and token_secret values in plain YAML configs and rewrites the file with encrypted blobs (while updating the running config) as soon as you connect successfully. That keeps legacy configs safe without forcing you to adopt a new workflow.

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

📚 Complete documentation is available in the docs/ folder

🔌 Usage

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

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

Default paths:

• Linux/macOS config: ~/.config/pvetui/config.yml
• Linux/macOS cache: ~/.cache/pvetui
• Windows config: %APPDATA%/pvetui/config.yml
• Windows cache: %LOCALAPPDATA%/pvetui

Windows legacy fallback:

• Existing ~/.config/pvetui/config.yml is still auto-detected.
• Existing ~/.cache/pvetui is still used if the newer %LOCALAPPDATA%/pvetui path does not exist.

Command Line Options

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

Key Bindings

Customize keys via the key_bindings section in your config. This includes task-panel controls (tasks_toggle_queue, task_stop_cancel) in addition to global navigation/actions. See docs/CONFIGURATION.md#key-bindings for all options (including macOS Opt key support).

🎨 Theming

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

📺 VNC Console Access

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.

🔧 Requirements

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

💡 Tips

• 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. Proxmox VE does not install sudo by default, so either install it (and grant your non-root ssh_user rights) or connect as root so commands run without sudo. Example sudoers line:

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

🛠️ Troubleshooting

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

🐳 Container Usage (Dev/Test)

Container-based runs are supported for development and testing workflows.

See docs/DOCKER.md for Docker/Podman details.

🗺️ Features Roadmap

Planned and actively prioritized:

• Role-aware operation mode: Compatibility with non-admin Proxmox roles (for example, "operator"-style permissions) with clear capability detection and graceful UI fallback when actions are not allowed.
• Expanded guest configuration management: Manage more guest settings directly in TUI, including common hardware and network options.
• Guest creation workflows: Guided creation for VMs/LXCs with safe defaults and validation.
• Storage management basics: Visibility and common actions for storage targets (capacity, content, and routine operations).

Under evaluation (higher complexity):

• SDN management: Valuable but broad in scope; likely to start with read-only visibility before write operations.
• Advanced cluster/network workflows: Additional orchestration features that may require phased rollout to keep UX predictable in TUI.

If a roadmap item is critical for your environment, open an issue with your use case and required Proxmox version.

🤝 Contributing

Contributions welcome! Check the issues page.

📝 License

MIT License - see LICENSE file for details.

This repository vendors assets from noVNC under MPL-2.0, BSD, SIL OFL, MIT, and CC BY-SA licenses. Refer to THIRD_PARTY_LICENSES.md for a full breakdown and include that file plus internal/vnc/novnc/LICENSE.txt (and sub-licenses) with any binary release artifacts to satisfy attribution and redistribution requirements.

™️ Trademark Notice

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.

Upgrading Embedded noVNC

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.