pvetui

A Terminal User Interface For Proxmox Virtual Environment

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

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
• Proxmox API Browser: Interactive Proxmox VE API reference at devnullvoid.github.io/pvetui-openapi
• Group Mode (multi-cluster): Combine multiple Proxmox profiles into one unified view with routed actions per cluster
• CLI Subcommands: Use pvetui non-interactively from scripts or AI agent workflows — list/show nodes, guests, and tasks; create and migrate VMs/LXCs; manage storage content, download templates and OCI images, and restore backups

📸 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

Linux DEB/RPM Packages:

Prebuilt .deb and .rpm packages are published with each GitHub release. Download the package for your architecture from Releases, then install it with your system package manager:

# Debian/Ubuntu
sudo apt install ./pvetui_*_linux_amd64.deb

# Fedora/RHEL/openSUSE
sudo dnf install ./pvetui_*_linux_amd64.rpm

Linux Package Repository (Cloudsmith):

# Debian/Ubuntu
curl -sLf 'https://dl.cloudsmith.io/public/devnullvoid/pvetui/cfg/setup/bash.deb.sh' | sudo bash
sudo apt update
sudo apt install pvetui

# Fedora/RHEL/openSUSE
curl -sLf 'https://dl.cloudsmith.io/public/devnullvoid/pvetui/cfg/setup/bash.rpm.sh' | sudo bash
sudo dnf install pvetui

Package repository hosting is graciously provided by Cloudsmith as free hosting for open-source projects.

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_keyfile: "~/.ssh/id_ed25519"   # Optional: SSH private key (defaults to SSH agent / standard paths)
    vm_ssh_keyfile: "~/.ssh/id_vm"     # Optional: key for QEMU VM shells (defaults to ssh_keyfile)
    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
# Optional per-group behavior:
group_settings:
  all-servers:
    mode: aggregate  # default: combine all member profiles
  prod-ha:
    mode: cluster    # connect to one healthy profile with automatic failover
debug: false
show_icons: true # Controls decorative TUI and startup/status message emoji prefixes

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_keyfile is optional; when omitted, pvetui uses the running SSH agent (SSH_AUTH_SOCK) if available, then falls back to ~/.ssh/id_ed25519, ~/.ssh/id_rsa, and ~/.ssh/id_ecdsa. vm_ssh_keyfile follows the same logic and falls back to ssh_keyfile. 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

• ansible: Global-menu Ansible toolkit with pvetui YAML/INI inventory generation, optional community.proxmox.proxmox dynamic inventory support, ad-hoc module execution, playbook execution, and SSH setup guidance
• community-scripts: Adds the popular Community Scripts installer to node context menus and CLI mode
• 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:
    - "ansible"
    - "community-scripts"
    - "command-runner"
    - "guest-insights"     # Guest Insights plugin (legacy alias: demo-guest-list)

The Ansible plugin defaults to pvetui's generated inventory. Advanced users can set plugins.ansible.inventory_source: community_proxmox to generate a temporary .proxmox.yml source for the community.proxmox.proxmox inventory plugin. pvetui derives non-secret connection fields (url, user, token_id) and password/token secret environment variables from the active profile when possible, so saved community inventory files can be reused outside pvetui without writing Proxmox secrets into them.

📖 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.”

Group Modes

Groups support two operating modes via group_settings:

• aggregate (default): combines resources from all profiles in the group.
• cluster: active/passive behavior for HA-style setups. pvetui connects through one healthy profile at a time and fails over automatically.

Example:

group_settings:
  all-servers:
    mode: aggregate
  prod-ha:
    mode: cluster

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 ca