Proxion

Try it in your browser: https://c2tech-sys.github.io/proxion/ (sample data, no install)

Proxion is a modern, open-source web console for Proxmox VE that overlays the stock UI: daily-driver views for the things you look at all day, vSphere-style object pages for VMs/CTs/nodes, an embedded console and terminal, and deep links back to the stock UI for everything else.

It's a pnpm monorepo: a Vite/React frontend, a Fastify API/proxy server, and a generated Proxmox VE API client. The read-only PVE proxy (/api/pve/*) is permanently write-blocked; the writes Proxion does perform -- guest power actions, rename/notes, snapshots, backup and restore, clone, convert to template, migrate, hardware edits, node reboot/shutdown, storage uploads and deletes, restore, clone, VM creation, migrate, hardware edits, node reboot/shutdown, storage uploads and deletes, console thumbnails and per-user preferences -- each go through their own allow-listed route, checked against your real PVE privileges -- see Feature status below.

Screenshots

Quickstart

Get from nothing to a running Proxion in one docker compose up.

1. Create a read-only PVE user + API token

Run on a Proxmox node as root (or an equivalently privileged user) -- this gives Proxion's live dashboard/task feed just enough to read your cluster, plus console access for the embedded VNC/terminal bridges:

pveum role add ProxionReadOnly -privs "Datastore.Audit,Mapping.Audit,Pool.Audit,SDN.Audit,Sys.Audit,VM.Audit,VM.Console"
pveum user add proxion@pve
pveum aclmod / -user proxion@pve -role ProxionReadOnly
pveum user token add proxion@pve dev --privsep 0

The last command prints the token's secret once -- copy it somewhere safe; you'll paste it into .env as PVE_TOKEN_SECRET below (PVE_TOKEN_ID is proxion@pve!dev). You still sign in to the app itself with your own PVE username/password (Proxion never stores it) -- this token is only for the always-on cluster poller.

2. Get your PVE cert's TLS fingerprint

PVE's default certificate is self-signed, so Proxion pins to it instead of either trusting a real CA or disabling verification:

pvenode cert info
# or: openssl s_client -connect pve.example.local:8006 </dev/null 2>/dev/null \
#       | openssl x509 -fingerprint -sha256 -noout

Copy the Fingerprint (sha256) value into PVE_TLS_FINGERPRINT below.

3. Configure and start

cp .env.example .env
# edit .env: PVE_URL, PVE_TLS_FINGERPRINT, PVE_TOKEN_ID, PVE_TOKEN_SECRET, SESSION_SECRET, ...
cp docker-compose.example.yml docker-compose.yml
docker compose up -d

docker-compose.example.yml pulls the published image (ghcr.io/c2tech-sys/proxion:0.1.0) by default; uncomment the build: . line instead if you'd rather build it locally from this checkout.

Open http://:3080 and sign in with your own PVE username and password.

Try it without a Proxmox host

No cluster handy? Run the UI against static fixtures instead -- no server, no PVE, no Docker:

pnpm install && pnpm demo

Production notes

• Put Proxion behind TLS -- see docs/deploy.md for reverse-proxy config (nginx/Caddy) and the Caddy + Azure DNS kit for a mesh-only deployment with a real Let's Encrypt certificate.
• Set a real SESSION_SECRET (openssl rand -hex 32) -- required in production.
• Review PROXION_COOKIE_SECURE if Proxion itself is served over plain HTTP behind something else that terminates TLS.
• The optional per-node host agent avoids a vncproxy task-log entry for every console thumbnail capture.
• Storage uploads stream through the Proxion container itself, so any reverse proxy in front of it must allow large request bodies (Caddy does by default); see PROXION_UPLOAD_MAX_BYTES below to cap the largest upload this server will forward to PVE.
• After a deploy, a tab left open from before the update shows a banner offering a reload once it notices the server is running a newer build than the tab itself.

Feature status

Reads go through a permanently read-only proxy. The writes this app performs -- guest power actions, rename/notes, snapshot create/delete/rollback, and migrate (below) -- each go through their own allow-listed route, gated on a signed-in session and the matching PVE privilege on that guest. Nothing else here can edit config or otherwise change your cluster -- /api/pve/* itself stays a read-only proxy.

Console thumbnails: host agent (optional)

By default console thumbnails are captured server-side over VNC, which logs a vncproxy task per capture. An optional per-node agent, agent/, takes the screendump straight from QEMU's QMP socket instead, avoiding that VNC session and task log entry entirely; see its README for the install and security details.

Architecture

flowchart LR
    subgraph Browser
        UI["Proxion web app<br/>React + Vite"]
    end

    subgraph Server["Proxion server (Fastify)"]
        API["REST /api/*<br/>+ SSE /api/events"]
        WS["Websocket bridges<br/>/ws/vnc/*, /ws/term/*"]
        Poller["Cluster poller"]
    end

    subgraph PVE["Proxmox VE cluster"]
        PVEAPI["PVE REST API<br/>/api2/json"]
        PVEWS["PVE console websockets<br/>vncwebsocket"]
    end

    UI -- "JSON over HTTPS" --> API
    UI -- "SSE (resource/task diffs)" --> API
    UI -- "websocket (console/terminal)" --> WS
    API -- "pass-through session ticket<br/>or service token" --> PVEAPI
    Poller -- "service token, polled" --> PVEAPI
    WS -- "ticket-authenticated" --> PVEWS

• The browser never talks to Proxmox directly -- everything goes through the Proxion server, which resolves each request to either the caller's own PVE session ticket (pass-through login) or, for the shared dashboard/task feed, an optional read-only service token.
• PVE tickets never reach the browser: starting a console session returns an opaque, single-use, 60-second-TTL id instead.
• The web app can also run against static fixtures with no server or PVE host at all (VITE_USE_FIXTURES=1) -- useful for a demo or for frontend work with no lab handy.

See docs/architecture.md for a one-page deeper look at the auth model, the read-only proxy vs. the allow-listed actions route, the console bridges, and the thumbnails/preferences stores.

Local development

Running Proxion in Docker? See Quickstart above and docs/deploy.md for every environment variable, reverse-proxy notes (websockets must be proxied for the console/ terminal to work), and the recommended read-only service-token role. This section is for working on Proxion itself.

Requirements: Node >= 24, pnpm (corepack enable picks up the version pinned in package.json).

pnpm install
pnpm dev

• Web app: http://localhost:5173 (Vite dev server; /api and /ws are proxied to the server)
• Server API: http://localhost:3080 (health check at /api/health)

No Proxmox host handy? Demo the UI against static fixtures instead:

pnpm demo   # fixture-mode UI, no Proxmox needed (any shell)

Other scripts: pnpm build, pnpm typecheck, pnpm lint, pnpm test, pnpm format. On a busy machine, PROXION_VITEST_WORKERS=<n> caps the web suite's vitest workers.

Workspace layout

• apps/web -- @proxion/web, the React UI (Vite, Tailwind v4, shadcn/ui, TanStack Router/Query).
• apps/server -- @proxion/server, the Fastify API/proxy server.
• packages/pve-api -- @proxion/pve-api, the generated Proxmox VE API client.

Notifications

Proxion can announce alerts (failed tasks, backup incidents, storage over the configured threshold) as they open, escalate, resolve or clear -- over a webhook and/or email -- instead of only showing them on the dashboard. Off by default; set any of the env vars below to enable a channel. Multiple transitions within a short window are batched into one message per channel, and a restart never re-announces something it already told a channel about (state persists to <PROXION_DATA_DIR>/notify-state.json).

Discord (PROXION_NOTIFY_WEBHOOK_FORMAT=discord): create a channel webhook (Channel Settings -> Integrations -> Webhooks) and set PROXION_NOTIFY_WEBHOOK_URL to its URL -- no token needed.

ntfy (PROXION_NOTIFY_WEBHOOK_FORMAT=ntfy): PROXION_NOTIFY_WEBHOOK_URL=https://ntfy.sh/your-topic (self-hosted ntfy works the same way); set PROXION_NOTIFY_WEBHOOK_TOKEN if your topic requires auth.

Email: PROXION_NOTIFY_SMTP_URL=smtps://user:pass@smtp.example.com:465, PROXION_NOTIFY_EMAIL_FROM=proxion@example.com, PROXION_NOTIFY_EMAIL_TO=ops@example.com.

Each channel gets a formatted message rather than a text blob: email is an HTML message (plain-text alternative included) with one card per alert -- a severity-coloured edge, the guest, node and time, and an "Open in Proxion" button when PROXION_PUBLIC_URL is set; Discord gets one embed per alert; Slack gets blocks (a header, then a section, meta line and divider per alert); ntfy gets a Markdown body with a click action that opens the alert; Gotify gets Markdown too (and a click URL). The generic webhook stays plain JSON, now with a headline, highestSeverity, sentAt and a label/color/guestName/guestType on each event. Very large batches are cut off with an "...and N more" line.

The webhook token and the SMTP URL's embedded credentials are never written to the server's logs -- a channel failure logs only the channel name and host.

Webhook destinations. Proxion assumes the people who can change notification settings (Sys.Modify on /) are trusted operators, so a webhook or SMTP server on your LAN (a self-hosted ntfy or Gotify, an internal mail relay) is fine and private addresses are not blocked. Two safeguards apply regardless: a webhook request never follows a redirect (a 3xx is a failure, so a token is never sent to a place you did not configure), and "Send test notification" reports a failure only as request failed (HTTP <status>), (timeout) or (network) -- never a host, port, status text or response body -- so it cannot be used to probe other machines. To restrict where notifications can go, set PROXION_NOTIFY_ALLOWED_HOSTS to a comma-separated list of host names (case-insensitive, exact match, a trailing dot is ignored, *.example.com matches exactly one extra label, ports are not compared). When set, saving a webhook or SMTP URL on any other host is refused, and a saved destination that no longer matches (for example after you tighten the list) is dropped at startup with a warning that names the setting but not the host. Unset means no restriction. A list that cannot be parsed (for example one with a port, hooks.example.com:443) fails closed: no destination is allowed, nothing is sent, saving is refused, and the Preferences page shows the error until you fix proxion.env and redeploy.

The Preferences page shows which channels are configured and has a "Send test notification" button (a signed-in session only; disabled with a shared service token, same as every other write in token mode) -- GET /api/notify/status / POST /api/notify/test. A bad notification value disables notifications and shows why on the Preferences page; it never stops the server.

Managing notifications in the app. A user with Sys.Modify on / can manage all of this on the Preferences page, without editing the env file: a master switch, snooze buttons (1 h, 8 h, 24 h, 7 days, Unmute), which alert kinds are announced (backups, failed tasks, storage usage), the delivery settings above, and the webhook and email details. The environment variables above stay the defaults: until someone saves from the page, they are what is in effect; the first save (or snooze) writes the whole effective configuration to <PROXION_DATA_DIR>/notify-settings.json, and from then on that file wins and takes effect at once, without a restart. The file holds the webhook token and the SMTP URL (with its password) in plain text, so it is written with mode 0600 in the data directory -- keep that directory private and out of backups you do not trust. The API never returns a secret: GET /api/notify/settings (any signed-in identity) shows the webhook's host only, whether a token is set, and the SMTP host/port/user. PUT /api/notify/settings and POST /api/notify/mute need a signed-in session (not the shared service token) and Sys.Modify on /. While notifications are switched off or snoozed nothing is sent, but alert state keeps being tracked, so nothing that happened meanwhile is announced when they come back; "Send test notification" always sends, even while muted.

Security model

• Pass-through login: Proxion never asks for or stores your PVE password. Logging in calls PVE's own POST /access/ticket with the credentials you type, and only the resulting ticket is kept -- in memory, server-side, keyed by an opaque session id.
• No stored PVE secrets, except an optional read-only service token (PVE_TOKEN_ID/PVE_TOKEN_SECRET) used for the always-on cluster poller/dashboard feed. See docs/deploy.md for the recommended minimal-privilege role for that token.
• TLS fingerprint pinning: since PVE's default certificate is self-signed, Proxion can pin to it by SHA-256 fingerprint (PVE_TLS_FINGERPRINT) instead of either trusting a real CA or disabling verification outright (PVE_TLS_INSECURE, discouraged).
• Signed, httpOnly session cookies: the session cookie is httpOnly, SameSite=Lax, signed with SESSION_SECRET, and Secure by default in production.
• Read-only phase: the proxy hard-rejects any non-GET request to /api/pve/* (405), independent of the PVE user's actual permissions -- Phase 1 cannot write to your cluster even if the credentials used could.
• Console tickets never reach the browser as PVE tickets: starting a console/terminal session returns an opaque, single-use, 60-second-TTL id that the server maps to the real upstream connection.

See SECURITY.md to report a vulnerability.

Roadmap

• Phase 1: read-only. Dashboard, inventory, object pages, monitoring graphs, task feed, console/terminal bridges. Done.
• Phase 1.5: the first slice of writes -- guest power actions (start/stop/shutdown/reboot/pause/resume), console thumbnails, and per-user preferences, all gated behind the caller's real PVE permissions; /api/pve/* itself stays a permanently read-only proxy. Done.
• Phase 2 (current): more actions, each as its own allow-listed route, same pattern as guest power actions. Rename/notes, snapshot create/rollback/delete and the cluster-wide Guests list shipped in 0.2; migrate, node reboot/shutdown and the storage browser shipped in 0.3; backup/restore and clone followed.
• Phase 3: VMware-style extras -- console thumbnails in the inventory tree itself (done: a hover card on each running guest row, alongside the existing dashboard and VM/CT Summary previews), a built-in SSH client for nodes/guests, alarms/alerting, and a storage browser.

How it's built

Proxion started as a tool for my own Proxmox cluster, and I run it there every day. I build it together with Claude (Anthropic's Claude Code): I set the direction, decide what ships, review the changes and test them against a real host; Claude writes a large share of the code. I'd rather say that up front than have you find it in the commit history.

Every change goes through the same gates before it is tagged and published: a TypeScript typecheck across the workspace, ESLint with zero warnings, the unit and render test suites (over 800 tests, run against a fake PVE and fixture data, never a live host), and CI on GitHub. Releases build the multi-arch image from the tagged commit.

Found a bug? Open an issue. Fixes land quickly, and each one gets a test so it stays fixed.

Support the project

Proxion is free and open source. If it saves you time, you can buy me a coffee -- it keeps the lab running and the features coming.

License

Apache License 2.0 -- see LICENSE. See NOTICE for third-party attributions (Proxmox VE, noVNC, xterm.js, uPlot, Josefin Sans, Open Sans).

Proxion is an independent, unofficial project and is not affiliated with or endorsed by Proxmox Server Solutions GmbH.