pvetui

README

pvetui

A Terminal User Interface For Proxmox Virtual Environment

Pronounced: peeve-tooey

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
• Community Scripts: Install Proxmox community scripts directly from the TUI
• 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

📸 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

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.

From Source:

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

Note: The go install github.com/devnullvoid/pvetui/cmd/pvetui@latest command does not work because it doesn't fetch git submodules required for the embedded noVNC client. Use the source installation method above instead.

🔧 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"

  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

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.

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.

📖 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

Command Line Options

Flag	Short	Description
--config	-c	Path to YAML config file
--profile	-p	Connection profile to use (overrides default_profile)
--no-cache	-n	Disable caching
--version	-v	Show version information
--config-wizard	-w	Launch interactive config wizard and exit
--addr		Proxmox API URL
--user		Proxmox username
--password		Proxmox password
--token-id		Proxmox API token ID
--token-secret		Proxmox API token secret
--realm		Proxmox realm
--insecure		Skip TLS verification
--api-path		Proxmox API path
--ssh-user		SSH username
--debug		Enable debug logging
--cache-dir		Cache directory path

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

Key Bindings

Key	Action	Key	Action
h j k l	Navigate	Alt+1/2/3	Switch views
Enter	Select	[ ]	Previous/Next view
s	SSH Shell	v	VNC Console
m	Context Menu	g	Global Menu
/	Search	a	Auto-refresh
?	Help	q	Quit

Customize keys via the key_bindings section in your config. 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. 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

🐳 Docker Usage

git clone --recurse-submodules 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.

🤝 Contributing

Contributions welcome! Check the issues page.

📝 License

MIT License - see LICENSE file for details.

™️ 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.