Prox

Simple CLI for Proxmox VE. Focus on: zero required --node flags (auto discovery), safe VM/CT lifecycle, secure encrypted config, fast migration & clear describe output.

Contents

• Why Prox?
• Install
• Quick Start
• Core Commands
• Flags Cheat Sheet
• Security
• Advanced Docs
• Contributing
• Releases
• License
• Support

Why Prox?

Key capabilities:

• Auto node discovery (omit --node 99% of the time)
• VM: list | start | shutdown | clone (full/linked) | migrate (online/offline, local disks) | edit | describe | delete
• Container (LXC): create (template shortcuts + SSH key injection), list, start/stop, describe
• Rich describe output: IP discovery (guest agent / DHCP / static), disks, resources, uptime
• Secure encrypted credential storage (AES‑256, automatic legacy migration)
• SSH key validation (file or stdin, multi‑key, type checks)
• Clear progress + helpful errors
• Modular Go codebase (easy to extend) + Makefile automation

Install

Prereqs: Go 1.21.6+, access to Proxmox VE.

git clone https://github.com/scotty-c/prox.git
cd prox
make build        # outputs ./bin/prox
./bin/prox --help

Alt (quick):

go install github.com/scotty-c/prox@latest
prox --help

Docker / compose usage: see DOCKER.md.

Quick Start

Configure (stored encrypted):

prox config setup -u admin@pam -p secret -l https://proxmox.example.com:8006

VM workflow:

prox vm list
prox vm start 100
prox vm describe 100          # shows IPs, disks, resources
prox ssh 100                  # Add/update SSH config entry for VM 100
prox ssh --list               # List managed SSH config entries
prox ssh 100 --delete         # Remove SSH entry for VM 100
prox vm clone 100 101 clone-101 --full
prox vm migrate 100 node2 --online
prox vm shutdown 100
prox vm delete 101

Container workflow:

prox ct templates
# create: prox ct create <name> <template>
prox ct create web ubuntu:22.04 --ssh-keys-file ~/.ssh/id_rsa.pub --memory 1024 --disk 10
prox ct start web
prox ct describe web
prox ssh web          # Add/update SSH config entry for container
prox ct stop web

Advanced examples:

# Multiple SSH keys via stdin
cat ~/.ssh/id_*.pub | prox ct create --name build --template alpine:3.18 --ssh-keys-file -
# Edit VM resources
prox vm edit 100 --cpu 4 --memory 8192
# Complex migration
prox vm migrate 100 node2 --online --with-local-disks
# SSH setup with custom configuration
prox ssh web-server --user admin --port 2222 --key ~/.ssh/production_key
# Preview SSH entry creation/update
prox ssh web-server --dry-run
# Preview deletion (no file change)
prox ssh web-server --delete --dry-run

Pro tips:

• Skip --node: auto discovery handles it
• Aliases: describe→desc/show, delete→del/rm, shutdown→stop
• Template shortcuts: ubuntu:22.04 | debian:12 | alpine:3.18
• SSH key file can include multiple lines (each a key)
• Use prox ssh <resource> --dry-run to preview SSH config changes
• Use prox ssh --list to view current managed entries
• Use prox ssh <resource> --delete [--dry-run] to remove an entry safely

Core Commands

Config:

prox config setup -u user -p pass -l https://host:8006
prox config read     # masked
prox config update
prox config delete

VMs:

prox vm list | describe <id> | start <id> | shutdown <id> | delete <id>
prox vm clone <srcID> <newID> [NAME] [--full]
prox vm edit <id> --cpu 4 --memory 8192
prox vm migrate <id> <targetNode> [--online] [--with-local-disks]

Containers:

prox ct list | templates
# create: prox ct create <name> <template>
prox ct create api debian:12 --ssh-keys-file ~/.ssh/id_rsa.pub --memory 2048
prox ct start api; prox ct describe api; prox ct stop api

SSH Configuration:

# Add or update entry (VM or CT by name or ID)
prox ssh <vm-or-container-name-or-id>
# Custom options
prox ssh myvm --user root --port 22 --key ~/.ssh/id_rsa
# Dry-run (preview block, no write)
prox ssh 123 --dry-run
# List managed entries (table output similar to vm list)
prox ssh --list
# Delete an entry (by resource alias / name / ID)
prox ssh myvm --delete
# Dry-run delete
prox ssh myvm --delete --dry-run

Behaviour notes:

• Add/update: Rewrites (replaces) existing Host block matching the alias
• Delete: Safely removes only the targeted Host block; rest of config preserved
• List: Parses ~/.ssh/config and shows columns HOST | HOSTNAME | USER | PORT | IDENTITY
• Dry-run: Never modifies file (creation/update or deletion)

Flags Cheat Sheet (human-friendly)

Containers (ct)

• create: prox ct create

  • Positional args:
    • name: container name (e.g., web, api)
    • template: either shortcut (ubuntu:22.04, debian:12, alpine:3.18) or full volid (storage:vztmpl/...)
  • Flags:
    • -N, --name Alias for positional name (optional)
    • -t, --template Alias for positional template (optional)
    • -n, --node Create on a specific node (auto-resolves from template if omitted)

    • --vmid <id>              Explicit container ID (auto-generated if omitted)
      

    • -m, --memory Memory in MB (default 512)
    • -d, --disk Disk size in GB (default 8)
    • -c, --cores CPU cores (default 1)
    • -p, --password Root password (use with care)

    • --prompt-password        Prompt interactively for root password
      

    • --ssh-keys-file <path|-> Public SSH key(s) file, or '-' to read from stdin (multi-line supported)
      

    • Notes:
      • Prefer positional name/template. If both positional and flags are supplied and conflict, positional wins; a warning is printed.
    • Examples:
      • prox ct create web ubuntu:22.04 --ssh-keys-file ~/.ssh/id_rsa.pub --memory 1024 --disk 10
      • cat ~/.ssh/id_*.pub | prox ct create build alpine:3.18 --ssh-keys-file -
      • prox ct create ci debian:12 --vmid 9002 --cores 2

    • list

      • Flags: -n, --node ; -r, --running (only running)
      • Example: prox ct list --running

    • describe <name|id>

      • Flags: none

    • start <name|id> | stop <name|id> | delete <name|id>

      • Flags: none

    • templates

      • Flags: -n, --node

    • shortcuts

      • Flags: none (prints common shortcuts like ubuntu:22.04)

    VMs (vm)

    • list

      • Flags: -n, --node ; -r, --running; -i, --ip (show IPs); -d, --detailed (disk info)

    • describe <id|name>

      • Flags: -n, --node (optional)

    • start | shutdown

      • Flags: -n, --node (optional)

    • edit

      • Flags:
        • -n, --node
        • -N, --name
        • -c, --cpu
        • -m, --memory
        • -d, --disk

    • clone [NAME]

      • Flags: -n, --node ; -N, --name (optional); -f, --full (full clone)
      • Notes: If NAME is provided positionally and --name is also set and they differ, positional NAME takes precedence; a warning is printed.

    Nodes (node)

    • list

      • Command: prox node ls
      • Description: List cluster nodes in a compact table (NAME, STATUS, TYPE, ID). Matches the VM/CT table UX.
      • Flags: - none currently (node auto-discovery is used when relevant)
      • Example: prox node ls

    • describe <name|id> (alias: info)

      • Command: prox node describe <name|id> or prox node info <name|id>
      • Description: Show detailed information for a node: basic info, resource summary (CPU, memory, disk, uptime) and primary node IP if available.
      • Notes: Memory and disk are shown in GiB with percentages. Uptime is formatted as days/hours/minutes.
      • Example: prox node describe promox01

    Nodes (node)

    • list

      • Command: prox node ls
      • Description: List cluster nodes in a compact table (NAME, STATUS, TYPE, ID). Matches the VM/CT table UX.
      • Example: prox node ls

    • describe <name|id> (alias: info)

      • Command: prox node describe <name|id> or prox node info <name|id>
      • Description: Show detailed information for a node: basic info, resource summary (CPU, memory, disk, uptime) and primary node IP if available.
      • Notes: Memory and disk are shown in GiB with percentages. Uptime is formatted as days/hours/minutes.
      • Example: prox node describe promox01

    • Environment variable:

      • PROX_NODE can be set to specify a default node name for scripts/tests (see tests/e2e/config.env).

    • migrate

      • Flags: -s, --source ; --online; --with-local-disks

    • delete

      • Flags: -n, --node (optional)

    SSH (manage ~/.ssh/config entries)

    • prox ssh <vm-or-ct name|id>
      • Flags: -u, --user ; -p, --port ; -k, --key ; --dry-run; --list; --delete
      • Notes: --list and --delete are mutually exclusive with add/update mode

    Global config

    • prox config setup -u/--username -p/--password -l/--url

    Tip: run any command with --help for full details.

    Security

    • AES‑256 encryption for stored credentials (system/user bound)
    • Plaintext legacy configs auto‑migrated
    • Secure file perms (600)
    • See SECURITY.md for encryption details & migration command

    prox config migrate   # migrate legacy plaintext if present

    Advanced Docs

    • Architecture & package layout
    • Docker & container usage
    • Testing (E2E harness, categories)
    • Security deep dive
    • Contributing workflow

    Contributing

    PRs welcome. See CONTRIBUTING.md (branch from main, add tests, run make release-check).

    Releases

    GitHub Actions builds & publishes multi‑arch binaries + Docker images on version tags (vX.Y.Z). Check the Releases page.

    License

    Apache 2.0 (see LICENSE).

    Support

    Open an issue / discussion. Ensure your Proxmox account has rights for VM + CT operations. Include CLI version (prox --version) and command output when reporting problems.

    ---

    Enjoy fast, safe Proxmox management with Prox.