Convoy: a KVM management panel for Proxmox hosting businesses

A panel for selling Proxmox capacity, not for administering one node

Convoy is described as a KVM server management panel for hosting businesses, built with PHP and React, and it wraps around Proxmox rather than replacing it. That framing sets the audience precisely. Someone with a single Proxmox server for their own use already has the Proxmox web interface and does not need this. Someone running Proxmox as a product does need something else, because Proxmox's own interface is an operator tool and not a customer portal, and because the commercial workflow involves billing, quotas, resource pools and support tickets that no hypervisor UI covers. The project is built on proven technology in the view of its own description, which is aimed at making it easier to drop into an existing system rather than replace one. The commercial model is stated plainly in the project description: a subscription at $6 per node per month for commercial use, and free for personal and non-profit use.

One install command, and a documentation split for the details

The installation story is short, which is the point of the design. Convoy installs onto a dedicated host with a single command that pipes a remote script into a shell. The details that the single command hides live in two files in the repository: a deployment document covering requirements, TLS, upgrades and running against an external database, and a configuration document listing every supported setting. The naming of those two files tells you what the project considers the two hard problems for an operator, and the fact that the application is expected on a dedicated host is worth taking seriously, since a panel that manages virtual machines is a component you would not want sharing a box with much else. The project homepage is convoypanel.com and the panel documentation is hosted separately at docs.convoypanel.com.

curl -fsSL https://install.convoypanel.com | sudo bash

Five containers, one image, and a worker that everything depends on

The production stack is defined in a compose file and the header comment explains the shape of the system better than any feature list would. There are five containers. The first three are the same image running different commands, and all of them read their configuration from the same .env file. The web container serves the panel and terminates TLS. The worker runs the queue, and the comment is blunt about the consequence: every Proxmox action is a job, so nothing works without it. The scheduler runs the timed jobs defined in routes/console.php, including the per-minute polls behind the node status indicators. Postgres holds the data and Redis backs the queue, the cache and the sessions. The Dockerfile comment adds the reason there is only one image: the difference between a bundled and an external database is which host DB_HOST points at, not which artifact you run.

Redis is not optional and the session lifetime is deliberately long

The environment example states that Redis is required rather than optional, because Horizon, the cache and the sessions all use it, and the corresponding settings set the cache store, the queue connection and the session driver to redis. One default is worth understanding because it changes how the panel feels. The session lifetime is set to 525600 minutes, which is a year, and the comment explains why: the Laravel default of two hours signs operators out of the panel far too aggressively for the way it is actually used. A separate comment on the database variables flags the same theme, since the database, Redis, mail and Xdebug settings all appear in the same file. The .env reference holds the complete annotated list of variables, while the example file holds the ones you actually need for a working install, and the distinction is the useful part.

DB_CONNECTION=pgsql
DB_HOST=database
DB_PORT=5432
DB_DATABASE=convoy
DB_USERNAME=convoy_user

REDIS_HOST=redis
REDIS_PORT=6379

CACHE_STORE=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis

TLS termination and the bare IP problem

The web container runs unprivileged and cannot bind port 80 or 443 inside the container, so the standard ports map to its 8080 and 8443. There is also a UDP line for HTTP/3, and the automatic certificate setting is what decides whether you get a real certificate or a self-signed one. The value defaults to on, and the comment explains the constraint precisely: it needs APP_DOMAIN to be a domain name that resolves to the host, because certificate authorities do not issue for bare IP addresses, so the installer turns it off and falls back to a self-signed certificate when you give it an IP address. Both the HTTP and HTTPS server addresses are built from APP_DOMAIN, and the parameter expansion is set to fail loudly when that variable is missing from the.env file, which is a good default for a required setting.

Local development runs on ddev with Postgres 17

For developers the project uses ddev, with Postgres 17, and the local environment is driven through a handful of commands. The sequence brings up the containers, installs the PHP dependencies, runs the database migrations, and then installs and builds the frontend assets, with a variant for hot module replacement. The application is served at the convoy.ddev.site hostname. The AGENTS.md file at the repository root covers the details that matter for contributors, including running Artisan, Composer and npm, regenerating the typed frontend artifacts, and taking database snapshots. The frontend build is a Vite build with a typecheck script that runs the TypeScript compiler in no-emit mode, and a mail workspace with its own install and build scripts, which tells you the transactional email templates are a separate bundle rather than part of the main frontend.

ddev start
ddev composer install
ddev artisan migrate
ddev npm install && ddev npm run build   # or: ddev npm run dev for HMR

What the project is not, and where the risks sit

Two limits deserve plain statement. The first is licensing. Convoy is licensed under a proprietary licence of its own, and while personal and non-profit use is described as free, commercial use is a paid subscription, so a hosting business has to have a signed agreement in place before deployment, and the licence file in the repository, not the marketing copy, is what governs. The second is that a panel like this holds the credentials to your hypervisor. It is designed to talk to Proxmox, to create and manage virtual machines on your behalf, and to poll node status every minute. That makes it a high-value target and makes the security of the install script, the panel login and the Proxmox account behind it the parts to review first. The dependency stack also deserves attention: the base image is serversideup/php, pinned by digest so rebuilds are reproducible, with project files added in a separate layer rather than by editing the upstream scripts.

Maintenance state, release channel and upgrade path

The repository is not archived, and the last push was on 2026-10-16. The recent tags are release candidates rather than finals, with v4.7.0-rc.1 on 2026-09-20, rc.2 on 2026-09-29 and rc.3 on 2026-10-16, which tells you two things: a major version is in preparation, and the release candidates are what has been published lately. A changelog file at the repository root and a separate deployment document covering upgrades are the two places to look when moving between versions. The repository also carries a contributor licence agreement, a notice file and a code of conduct, and a CHANGELOG alongside a CLAUDE.md file, so the tooling conventions around the project are written down. The default branch is main, and the test suite is wired into a workflow, with a status badge for it in the project description.

Editorial conclusion

Adopt Convoy if you resell Proxmox capacity and need a customer-facing control panel for virtual machines, with a web interface, a worker that carries out every Proxmox action, and a scheduler for timed jobs. Do not adopt it as a free self-hosted panel for a handful of your own VMs, because the licence is proprietary and priced per node per month for commercial use, and the Proxmox credential handling it requires is a real operational risk. Before you install, read the deployment notes for TLS, upgrades and external database support, decide whether you will run your own Postgres and Redis or use the bundled ones, and confirm that APP_DOMAIN resolves to the host because automatic certificates are not issued for a bare IP address.

Frequently asked questions

Official sources

1. ConvoyPanel/panel on GitHub
2. Issues
3. Project website
4. README
5. Releases