proxmox-tui

README

Proxmox TUI

A powerful Terminal User Interface for Proxmox VE clusters

Features • Screenshots • Installation • Configuration • Authentication • Usage

🚀 Overview

Proxmox TUI provides a sleek, efficient way to manage your Proxmox Virtual Environment directly from your terminal. Built with Go, it offers a modern terminal interface that combines the speed of CLI with the intuitive navigation of a GUI, featuring intelligent caching and flexible authentication options.

Say goodbye to slow web interfaces and hello to lightning-fast cluster management right where you work - in the terminal.

✨ Features

Proxmox TUI transforms your terminal into a powerful Proxmox management console with:

Comprehensive Cluster Management

Experience your entire Proxmox ecosystem at a glance with real-time cluster status, resource usage metrics, and node health indicators. The intuitive interface provides immediate visual feedback on your infrastructure's state.

Smart Guest Management

Manage your VMs and containers with an intelligent display that prioritizes running guests at the top with clear visual indicators. Stopped guests appear with dimmed text, creating an intuitive visual hierarchy that helps you focus on what matters.

Advanced Caching System

Enjoy responsive performance thanks to the BadgerDB-powered local caching system that intelligently stores and refreshes API responses. This significantly improves speed for repeated operations while ensuring data accuracy.

Flexible Authentication

Choose between traditional username/password authentication with automatic ticket renewal or more secure API token authentication with no expiration. The system automatically detects and uses your preferred method.

Interactive Shell Integration

Open SSH shells directly to Proxmox nodes, QEMU VMs, and LXC containers without leaving the interface, streamlining your workflow and eliminating context switching.

VNC Console Access

Seamlessly connect to VMs and nodes through VNC consoles that open directly in your default browser. Access QEMU VM consoles and node shell sessions through Proxmox's built-in noVNC interface without manual URL construction.

Community Scripts Support

Install and manage scripts from the Proxmox Community Scripts repository directly to your nodes, extending functionality with community-contributed tools.

📸 Screenshots

Node Management View - Detailed node information and status

Guest Management View - Real-time monitoring of VMs and containers

🔧 Requirements

• Go (version 1.20 or later recommended)
• Access to a Proxmox VE cluster
• SSH access to nodes/guests (for shell functionality)

📦 Installation

From Source

# Clone the repository
git clone https://github.com/devnullvoid/proxmox-tui.git
cd proxmox-tui

# Run the application directly
go run ./cmd/proxmox-tui -config ./configs/config.yml

# Build the application
go build -o proxmox-tui ./cmd/proxmox-tui

# Run the application
./proxmox-tui -config ./configs/config.yml

Pre-compiled Binaries

Pre-compiled binaries for various platforms are available on the Releases page.

Download and Install

1. Go to the Releases page
2. Download the appropriate binary for your platform:
   • Linux AMD64: proxmox-tui-linux-amd64.tar.gz
   • Linux ARM64: proxmox-tui-linux-arm64.tar.gz
   • macOS Intel: proxmox-tui-darwin-amd64.tar.gz
   • macOS Apple Silicon: proxmox-tui-darwin-arm64.tar.gz
   • Windows: proxmox-tui-windows-amd64.zip
3. Extract the archive:

   # For Linux/macOS
   tar -xzf proxmox-tui-*.tar.gz
   
   # For Windows
   # Extract using your preferred zip tool
   

4. Make executable (Linux/macOS only):

   chmod +x proxmox-tui-*
   

5. Run the application:

   ./proxmox-tui-* -config /path/to/your/config.yml
   

⚙️ Configuration

Proxmox TUI offers flexible configuration through YAML files, environment variables, and command-line flags. Configuration follows this precedence order (highest to lowest):

1. Command-line flags
2. Configuration file
3. Environment variables

Configuration File

Create a config.yml file with your Proxmox connection details:

# Basic connection settings
addr: "https://your-proxmox-host:8006"
api_path: "/api2/json"
insecure: false  # Set to true to skip TLS verification (not recommended for production)

# Authentication (choose one method)
user: "your-api-user"
realm: "pam"

# Method 1: Password authentication
password: "your-password"

# Method 2: API Token authentication (recommended)
token_id: "your-token-id"
token_secret: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Additional settings
ssh_user: "your-ssh-user"
debug: false
cache_dir: "~/.proxmox-tui/cache"

🔐 Authentication

Proxmox TUI supports two authentication methods:

Username/Password Authentication

Uses Proxmox's ticket-based authentication with automatic renewal every 2 hours. Simple to set up but requires storing your password.

API Token Authentication (Recommended)

Uses Proxmox API tokens for enhanced security with these benefits:

• No expiration (unless manually revoked)
• Granular permission control
• Better for automation and long-running sessions
• More secure than password-based authentication

Creating API Tokens in Proxmox

1. Log into your Proxmox web interface
2. Navigate to Datacenter → Permissions → API Tokens
3. Click Add to create a new token
4. Set the User (e.g., root@pam)
5. Enter a Token ID (e.g., proxmox-tui)
6. Decide whether to check Privilege Separation (unchecked gives the token the same permissions as the user)
7. Click Create
8. Important: Copy both the Token ID and Secret as the secret will only be shown once

🖥️ Usage

Run Proxmox TUI with your configuration file:

./proxmox-tui -config /path/to/your/config.yml

Keyboard Navigation

• F1: View Nodes
• F2: View Guests
• /: Search/Filter
• S: Open Shell
• V: Open VNC Console
• C: View Community Scripts
• M: Open Menu
• Tab/Next Tab: Switch between tabs
• Q: Quit

VNC Console Features

• Node VNC Shell: Access node shell sessions through VNC (available for all online nodes)
• VM VNC Console: Connect to QEMU VM consoles through VNC (available for running QEMU VMs)
• Browser Integration: VNC sessions open automatically in your default browser
• Secure Connection: Uses Proxmox's built-in authentication and VNC proxy system
• Cross-Platform: Works on Windows, macOS, and Linux

🤝 Contributing

Contributions are welcome! Feel free to submit issues or pull requests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.