{"id":50755171,"url":"https://github.com/zimmra/proxbootmanager","last_synced_at":"2026-06-11T04:02:02.965Z","repository":{"id":359657326,"uuid":"1246143998","full_name":"zimmra/ProxBootManager","owner":"zimmra","description":"Visual boot order manager for Proxmox VE - manage VM/LXC autoboot and startup order via a modern web UI","archived":false,"fork":false,"pushed_at":"2026-05-22T21:32:45.000Z","size":148,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T22:33:41.296Z","etag":null,"topics":["boot-manager","homelab","proxmox","proxmox-ve"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zimmra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T23:15:38.000Z","updated_at":"2026-05-22T22:15:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zimmra/ProxBootManager","commit_stats":null,"previous_names":["zimmra/proxbootmanager"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zimmra/ProxBootManager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimmra%2FProxBootManager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimmra%2FProxBootManager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimmra%2FProxBootManager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimmra%2FProxBootManager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zimmra","download_url":"https://codeload.github.com/zimmra/ProxBootManager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zimmra%2FProxBootManager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34181555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boot-manager","homelab","proxmox","proxmox-ve"],"created_at":"2026-06-11T04:02:01.966Z","updated_at":"2026-06-11T04:02:02.948Z","avatar_url":"https://github.com/zimmra.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ProxBootManager\n\nProxBootManager is a lightweight web dashboard for managing Proxmox VE VM and LXC autoboot behavior from a clean, modern UI. It lets homelab admins see guests in one place, toggle `onboot`, edit Proxmox startup order/delay strings, and drag guests into the boot sequence they want without jumping through the full Proxmox interface.\n\n## What it does\n\n- Lists QEMU VMs and LXC containers for a configured Proxmox node.\n- Shows guest VMID, name, type, running/stopped status, autoboot state, boot order, and boot delay.\n- Toggles autoboot with optimistic UI updates.\n- Edits Proxmox startup strings such as `order=1,up=30,down=10`.\n- Supports drag-and-drop reorder with batch save to Proxmox.\n- Displays backend/Proxmox connection status and user-friendly error messages.\n- Ships with a Debian 12 LXC installer and systemd service.\n- Serves the production React frontend from the Express backend.\n\n## Architecture\n\n```text\nBrowser\n  |\n  v\nReact/Vite frontend (TailwindCSS + shadcn-style UI)\n  |\n  v\nNode.js/Express backend proxy\n  |\n  v\nProxmox VE API (https://\u003chost\u003e:8006/api2/json)\n```\n\n## Prerequisites\n\n- A Proxmox VE host/node reachable from the install target.\n- A Proxmox API token with permission to audit guests and update VM/LXC options.\n- A Debian 12 (Bookworm) **unprivileged** LXC container to run ProxBootManager.\n- Network access from the container to `https://\u003cPROXMOX_HOST\u003e:8006`.\n\n\u003e **Note:** The installer and systemd service run as `root` inside the container. In an unprivileged LXC, the container's root UID is mapped to an unprivileged host UID by Proxmox, so this is safe and expected.\n\n## Quick Install\n\nRun this as root inside a fresh Debian 12 LXC/container:\n\n```bash\nbash \u003c(curl -s https://raw.githubusercontent.com/zimmra/ProxBootManager/main/install.sh)\n```\n\nThe installer will install Node.js 20, clone/update the app in `/opt/proxbootmanager`, build the frontend and backend, prompt for Proxmox settings, create a systemd service, and start ProxBootManager on port `3001`.\n\nAfter install, open:\n\n```text\nhttp://\u003cLXC_IP\u003e:3001\n```\n\n## Configuration\n\nRuntime configuration lives in `/opt/proxbootmanager/backend/.env` for production installs. After editing it, restart the service:\n\n```bash\nsudo systemctl restart proxbootmanager\n```\n\n| Variable | Required | Example | Description |\n| --- | --- | --- | --- |\n| `PROXMOX_HOST` | Yes | `192.168.1.10` or `pve.example.local` | Proxmox host/IP without protocol or port. The backend connects to `https://\u003chost\u003e:8006/api2/json`. |\n| `PROXMOX_TOKEN_ID` | Yes | `root@pam!proxbootmanager` | Full Proxmox API token ID. |\n| `PROXMOX_TOKEN_SECRET` | Yes | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Proxmox API token secret. Never returned to the frontend. |\n| `PROXMOX_NODE` | Yes | `pve` | Proxmox node name whose VMs/LXCs should be managed. |\n| `PORT` | No | `3001` | HTTP port for the Express backend and production UI. |\n| `VERIFY_SSL` | No | `false` | Set `false` for self-signed Proxmox certificates; set `true` for trusted certificates. |\n| `NODE_ENV` | No | `production` | Enables production static frontend serving when set to `production`. |\n| `CORS_ORIGIN` | No | `http://localhost:5173` or `*` | Comma-separated allowed origins. Defaults to `*`; localhost dev origins are always included. |\n\n## How to Create a Proxmox API Token\n\n1. Log in to the Proxmox VE web UI.\n2. Go to **Datacenter → Permissions → API Tokens**.\n3. Click **Add**.\n4. Choose a user, for example `root@pam` or a dedicated user.\n5. Enter a token ID, for example `proxbootmanager`.\n6. Leave **Privilege Separation** enabled for least privilege, or disable it only if you understand the security implications.\n7. Copy the generated secret immediately; Proxmox shows it only once.\n8. Grant permissions under **Datacenter → Permissions**.\n\nMinimum practical permissions for the user/token:\n\n- `VM.Audit` — list/read guest data and config.\n- `VM.Config.Options` — update `onboot` and `startup` options.\n- `Datastore.Audit` — useful for inventory/read operations in many Proxmox setups.\n\nAlternatively, assign an existing role such as `PVEVMAdmin` to the relevant path (for example `/vms` or the target node) if that matches your security model.\n\nUse these values during install:\n\n```text\nPROXMOX_TOKEN_ID=root@pam!proxbootmanager\nPROXMOX_TOKEN_SECRET=\u003csecret copied from Proxmox\u003e\n```\n\n## Updating\n\nRun the installer again:\n\n```bash\nsudo bash /opt/proxbootmanager/install.sh\n```\n\nIt will pull the latest code, reinstall dependencies if needed, rebuild, preserve or optionally rewrite `.env`, and restart the systemd service.\n\nYou can also manually update:\n\n```bash\ncd /opt/proxbootmanager\nsudo git pull --ff-only\nsudo npm install\nsudo npm run build --prefix frontend\nsudo npm run build --prefix backend\nsudo systemctl restart proxbootmanager\n```\n\n## Service Management\n\n```bash\nsudo systemctl status proxbootmanager\nsudo journalctl -u proxbootmanager -f\nsudo systemctl restart proxbootmanager\n```\n\n## Development\n\nClone the repository:\n\n```bash\ngit clone https://github.com/zimmra/ProxBootManager.git\ncd ProxBootManager\nnpm install\n```\n\nConfigure the backend:\n\n```bash\ncp backend/.env.example backend/.env\n# edit backend/.env with your Proxmox settings\n```\n\nRun the backend in development mode:\n\n```bash\ncd backend\nnpm install\nnpm run dev\n```\n\nRun the frontend in another terminal:\n\n```bash\ncd frontend\nnpm install\nprintf 'VITE_API_BASE_URL=http://localhost:3001\\n' \u003e .env\nnpm run dev\n```\n\nDevelopment URLs:\n\n- Frontend: \u003chttp://localhost:5173\u003e\n- Backend API: \u003chttp://localhost:3001\u003e\n- Health check: \u003chttp://localhost:3001/api/health\u003e\n\nUseful checks:\n\n```bash\ncd backend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run build\nbash -n install.sh\n```\n\n## Tech Stack\n\n- **Frontend:** React, Vite, TypeScript, TailwindCSS, shadcn-style components, TanStack Query, Axios, dnd-kit, Sonner, Lucide icons.\n- **Backend:** Node.js, Express, TypeScript, Axios, dotenv, CORS.\n- **Deployment:** Debian 12 LXC, Node.js 20 LTS, systemd.\n- **Package management:** npm workspaces.\n\n## Security Notes\n\n- Proxmox credentials are read only by the backend from `.env`, which is stored at `/opt/proxbootmanager/backend/.env` with mode `600`.\n- `/api/config/status` reports whether required env vars are set, but does not expose secret values.\n- Use a Proxmox token with the least privileges needed for your environment.\n- The service runs as `root` inside an unprivileged LXC container. Proxmox maps the container's root UID to an unprivileged host UID, providing host-level isolation without requiring a separate service account inside the container.\n- If possible, run ProxBootManager on a trusted management network or behind your preferred reverse proxy/auth layer.\n\n## License\n\nSee [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzimmra%2Fproxbootmanager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzimmra%2Fproxbootmanager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzimmra%2Fproxbootmanager/lists"}