proxmux

A terminal UI for managing Proxmox VE, built with Ink and Bun.

Features

• Dashboard - Overview of cluster nodes with CPU, memory, and disk usage
• VM Management - List, start, stop, and reboot virtual machines
• Container Management - List, start, stop, and reboot LXC containers
• Console Access - SSH directly into containers via pct console
• Storage View - View storage pools and usage
• Detail View - Detailed info for VMs/containers including network, resources, and config
• Vim-style Navigation - Use j/k or arrow keys to navigate
• Responsive UI - Adapts to terminal size

Requirements

• Proxmox VE with API access
• API token (recommended) or user credentials

Installation

Homebrew (macOS/Linux)

brew install roshie548/tap/proxmux

npm

Requires Bun runtime.

bunx proxmux

Or install globally:

bun install -g proxmux
proxmux

Standalone Binary

Download the latest binary for your platform from Releases:

• macOS Apple Silicon: proxmux-darwin-arm64
• macOS Intel: proxmux-darwin-x64
• Linux x64: proxmux-linux-x64
• Linux ARM64: proxmux-linux-arm64
• Windows: proxmux-windows-x64.exe

chmod +x proxmux-*
./proxmux-darwin-arm64  # or your platform

From source

# Clone the repository
git clone https://github.com/roshie548/proxmux.git
cd proxmux

# Install dependencies
bun install

# Run
bun run start

Configuration

Create a config file at ~/.config/proxmux/config.json:

{
  "host": "https://your-proxmox-host:8006",
  "user": "root@pam",
  "tokenId": "your-token-id",
  "tokenSecret": "your-token-secret"
}

Creating an API Token in Proxmox

1. Go to Datacenter > Permissions > API Tokens
2. Click Add
3. Select user (e.g., root@pam)
4. Enter a Token ID (e.g., proxmux)
5. Uncheck "Privilege Separation" to inherit the user's permissions
6. Copy the token secret (shown only once)

Note: If you leave "Privilege Separation" checked, you must manually assign permissions to the token under Datacenter > Permissions. The token needs at minimum VM.Audit, VM.PowerMgmt, and Datastore.Audit on / (or specific paths) to list and manage VMs/containers.

Environment Variables

Alternatively, use environment variables:

export PROXMOX_HOST="https://your-proxmox-host:8006"
export PROXMOX_USER="root@pam"
export PROXMOX_TOKEN_ID="your-token-id"
export PROXMOX_TOKEN_SECRET="your-token-secret"

Keyboard Shortcuts

Global

Key	Action
1-4	Switch views (Dashboard, VMs, Containers, Storage)
Tab	Cycle through views
q	Quit
Ctrl+C	Quit

Navigation

Key	Action
j / ↓	Move down
k / ↑	Move up
Enter	Open detail view / Confirm action
Esc	Go back / Cancel

Actions

Key	Action
r	Refresh data
s	Start VM/Container
x	Stop VM/Container (with confirmation)
R	Reboot VM/Container (with confirmation)

Detail View

Key	Action
j / k	Navigate actions
Enter	Execute selected action
Esc / q	Go back to list

Console (Containers)

Select "Console (SSH)" in the detail view to open a pct console session. You'll see the container's login prompt. Press Ctrl+] or type exit to return to proxmux.

Development

# Run with hot reload
bun run dev

# Type check
bun run --bun tsc --noEmit

License

MIT License - see LICENSE for details.