---
name: proxmox-ve
title: Proxmox VE Administration
trigger: Proxmox VE, pve, proxmox container, LXC, VM management, pct command, pveam, imac-proxmox
description: Manage Proxmox VE hosts via CLI - CT/VM lifecycle, storage, networking, and common pitfalls with unprivileged containers.
---

# Proxmox VE Administration

## SSH Access
- Connect as `root@imac-proxmox` using the Hermes-session key at `~/.ssh/id_ed25519_imac_proxmox`
- If auth fails, check `ssh-agent` and add the key: `eval $(ssh-agent -s) && ssh-add ~/.ssh/id_ed25519_imac_proxmox`
- Always ask user permission before taking action on the Proxmox host.

## Finding the Next CT/VM ID
```bash
pvesh get /cluster/nextid
```

## Template Management
- List local templates: `pveam list local`
- List available upstream: `pveam available --section system`
- Download: `pveam download local <template-name>`

## Creating an LXC Container
```bash
pct create <vmid> local:vztmpl/<template> \
  --hostname <name> \
  --storage <storage-name> \
  --rootfs <storage>:<size> \
  --memory <MB> --cores <N> \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp \
  --unprivileged 1 --features nesting=1 \
  --password <temp-password>
```

Common options:
- `--storage hdd-data` or `local-lvm` - pick from `pvesh get /nodes/localhost/storage`
- `--rootfs hdd-data:8` - 8GB disk
- `--net0 name=eth0,bridge=vmbr0,ip=dhcp` - DHCP on vmbr0
- `--features nesting=1` - required for some apps

## Container Lifecycle
- `pct start <vmid>`
- `pct stop <vmid>`
- `pct reboot <vmid>`
- `pct shutdown <vmid>`
- `pct destroy <vmid>`
- `pct exec <vmid> -- <command>`
- `pct enter <vmid>` - interactive shell

## Storage & Network Discovery
```bash
# Available storages
pvesh get /nodes/localhost/storage --output-format json

# Network bridges
pvesh get /nodes/localhost/network --output-format json
```

## Critical Pitfall: TUN Device in Unprivileged Containers
Tailscale, WireGuard, and any VPN software need `/dev/net/tun`. Unprivileged LXC containers do NOT have this by default. Tailscale will fail with:
```
CreateTUN("tailscale0") failed; /dev/net/tun does not exist
```

### Fix
Add these two lines to `/etc/pve/lxc/<vmid>.conf`, then reboot the CT:
```
lxc.cgroup2.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file 0 0
```

After reboot, Tailscale/wireguard will start normally.

## Installing Inside CTs
Standard Debian/Ubuntu apt works. Pre-install `curl gnupg` before running install scripts. Some tools (e.g., Tailscale) ship their own install script that adds apt repos.

## Verification
- Check CT IP: `pct exec <vmid> -- ip addr show eth0`
- Check service status: `pct exec <vmid> -- systemctl status <service>`
- Read logs: `pct exec <vmid> -- journalctl -u <service> --no-pager -n 20`

## Tailscale Auth Inside CT
After fixing TUN, run `tailscale up` inside the CT. It prints a `https://login.tailscale.com/a/...` URL that the user must open on their device to authenticate. The command will block until approval or timeout.