Add-ons
What add-on scripts are, where each one runs, how they are updated, and a page for every script in tools/addon.
An add-on installs one extra piece of software onto a system that already
exists. The scripts live in
ProxmoxVE tools/addon/;
this section has one page for each of the 33 scripts there.
Every add-on is started the same way, with the script name in the URL:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/tools/addon/glances.sh)"How add-ons differ from container scripts
Container script (ct/) | Add-on (tools/addon/) | |
|---|---|---|
| Creates a container | Yes | No. It works on the system it runs on, or on a container you pick. The one exception is All Templates, which creates a plain container from a pveam template |
| Settings dialog and resource variables | Yes | No. Each add-on asks its own few questions in the terminal |
| Engine files it loads | core/build.func, which pulls in the rest of the engine | core/core.func, lib/tools.func, core/error_handler.func and api/api.func, sourced directly from the core repository. Dockhand loads only the first two |
| Update | update inside the container (/usr/bin/update) | Depends on the script: an update_ helper, a question when you run the script again, the package manager, or nothing. See below |
| Uninstall | Not part of the script; you delete the container | Many add-ons can remove themselves. Each page says whether, and what is left behind |
Add-ons are independent of each other and of the application in the container. They are not one uniform pattern either: prompts, update and removal differ from script to script, which is why each has its own page.
The two ways an add-on runs
On the Proxmox VE host
Four scripts call require_pve_host. Anywhere but on a Proxmox VE node they
stop with exit code 232; on a node they also check the Proxmox VE version.
- Tailscale and
NetBird act against a container:
you pick one from a list, the script edits
/etc/pve/lxc/<CTID>.confon the host and installs the software inside withpct exec. - All Templates creates a new container.
- Netdata installs onto the host itself.
Inside the container or VM
All other add-ons install onto the system whose shell you run them in. Open
the container's console (or pct enter <CTID> on the host) and run the
command there. How strictly a script checks its surroundings varies:
| Check | Behaviour | Scripts |
|---|---|---|
confirm_not_pve_host | On a Proxmox VE node the script prints a warning and asks Continue anyway? (y/N). Anything but y exits | Arcane, Coder Code Server, Coolify, CrowdSec, Dockge, Dokploy, Komodo, pyenv, Runtipi, Webmin |
Own warning when /etc/pve exists | Asks Continue anyway on the Proxmox host? (y/N) | File Browser, FileBrowser Quantum |
| No check | The script installs wherever it is started | The remaining add-ons |
Operating system checks vary in the same way. require_debian_like refuses
Alpine and any system without apt-get (exit code 238); other scripts carry
their own Alpine branch; a few do not check at all. The "Supported OS" line on
each page states what the script itself tests.
Running a script a second time
Most add-ons detect their own installation. Started again, they do not reinstall but ask, in this order:
Uninstall <name>? (y/N):
Update <name>? (y/N):Answering no to both ends the script with No action selected. A few scripts
use a menu or a 1/2/3 question instead, and some have no second-run
behaviour at all; the pages say which.
Most scripts with an update routine also accept type=update, which skips the
questions and updates directly (Dockhand, File Browser, FileBrowser Quantum,
Glances and phpMyAdmin do not):
type=update bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/tools/addon/jellystat.sh)"If the add-on is not installed, this exits with code 233.
How update finds add-ons
An add-on registers itself for updates by writing a small helper at install time:
#!/usr/bin/env bash
# Jellystat Update Script
type=update bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/tools/addon/jellystat.sh)"The file is /usr/local/bin/update_<name>, here
/usr/local/bin/update_jellystat. There is no registry beyond that file. You
can run the helper yourself at any time.
The container's update command looks for these helpers in two places:
-
After the application update.
run_addon_updatesin coreui/menu.funclists every/usr/local/bin/update_*file and asks for each one:Do you also want to update addon "jellystat"? (y/N) [60s]:yoryesruns the helper. Any other answer, or no answer within 60 seconds, skips it. A failing add-on update prints a warning and does not stop the others. -
When the application script was removed from the project.
misc/update.shthen explains that there is no application update, and still offers the add-on updates with the same question.
Three things to know about the first case:
- The question is asked after the application's
update_scriptfunction returns. Many container scripts end that function withexit, and then the add-on question is never reached. Run the helper directly in that case. - With
PHS_SILENT=1the add-on updates are skipped with a notice. Update applications on the host sets that variable, so it never updates add-ons. - The answer is read from the terminal (
/dev/tty).
Add-ons that write an update helper: Actual Budget Prometheus Exporter, AdGuardHome-Sync, Arcane, Coder Code Server, Copyparty, CronMaster, Immich Public Proxy, Jellystat, Nextcloud Exporter, OliveTin, Pi-hole Exporter, Portainer, Prometheus Paperless-NGX Exporter and qBittorrent Exporter. All others are updated by running the script again, by the package manager, or not at all.
Exit codes and diagnostics
| Code | Meaning for add-ons |
|---|---|
| 232 | A host-only add-on was started somewhere else |
| 233 | Update requested, but the add-on is not installed |
| 238 | Operating system not supported by this add-on |
The full list is on the exit codes page.
All add-ons except Dockhand call init_tool_telemetry, which reports that the script ran and how
it ended when diagnostics are enabled in
/usr/local/community-scripts/diagnostics. Without that file, or with
DIAGNOSTICS=no, nothing is sent. Runs that end with 232, 233 or 238 are
never reported.
All add-ons
"Where" is what the script enforces or expects: Host means it must run on the Proxmox VE node, Guest means inside the container or VM.
From the Proxmox VE host
| Add-on | What it does | Where |
|---|---|---|
| Tailscale | Installs the Tailscale client into a chosen container and gives it /dev/net/tun | Host, against a container |
| NetBird | Installs the NetBird client into a chosen Debian or Ubuntu container and gives it /dev/net/tun | Host, against a container |
| All Templates | Creates a container from any pveam template with fixed defaults | Host |
| Netdata | Installs or removes Netdata on the node itself | Host |
Docker management
| Add-on | What it does | Where |
|---|---|---|
| Portainer | Portainer CE as a Compose project; needs Docker already installed | Either; no check |
| Dockge | Dockge Compose stack manager | Guest |
| Dockhand | Dockhand Docker UI; needs Docker already installed | Either; no check |
| Arcane | Arcane Docker UI | Guest |
| Komodo | Komodo with MongoDB or FerretDB | Guest |
| Coolify | Coolify through its upstream installer | Guest |
| Dokploy | Dokploy through its upstream installer | Guest |
| Runtipi | Runtipi through its upstream installer | Guest |
Files and administration
| Add-on | What it does | Where |
|---|---|---|
| File Browser | Web file manager serving / | Guest; asks before running on a host |
| FileBrowser Quantum | The Quantum fork, serving / | Guest; asks before running on a host |
| Copyparty | File server with uploads and its own service user | Either; no check |
| Webmin | Webmin system administration UI | Guest |
| phpMyAdmin | phpMyAdmin next to an existing database server | Either; no check |
| Coder Code Server | VS Code in the browser | Guest |
| OliveTin | Web buttons for predefined shell commands | Either; no check |
| CronMaster | Web UI for cron jobs | Either; no check |
Monitoring and exporters
| Add-on | What it does | Where |
|---|---|---|
| Glances | System monitor with web UI | Either; no check |
| Actual Budget Prometheus Exporter | Metrics for Actual Budget | Either; no check |
| Nextcloud Exporter | Metrics for Nextcloud | Either; no check |
| Pi-hole Exporter | Metrics for Pi-hole | Either; no check |
| Prometheus Paperless-NGX Exporter | Metrics for Paperless-NGX | Either; no check |
| qBittorrent Exporter | Metrics for qBittorrent | Either; no check |
Application companions
| Add-on | What it does | Where |
|---|---|---|
| AdGuardHome-Sync | Copies one AdGuard Home configuration to replicas | Either; no check |
| Immich Public Proxy | Public share proxy for Immich, optional visitor uploads | Either; no check |
| Jellystat | Statistics for Jellyfin with a local PostgreSQL | Either; no check |
| SparkyFitness Garmin Microservice | Garmin bridge for SparkyFitness | Guest; only where /opt/sparkyfitness exists |
Security
| Add-on | What it does | Where |
|---|---|---|
| CrowdSec | CrowdSec engine and the iptables firewall bouncer | Guest |
Development tools
| Add-on | What it does | Where |
|---|---|---|
| pyenv | pyenv with Python 3.14, optional Home Assistant, ESPHome or Matter Server pre-releases | Guest |
| Homebrew | Homebrew (Linuxbrew) for a non-root user | Either; no check |
"Guest" in these tables covers the scripts that warn and ask before running on a Proxmox VE node. "Either; no check" means the script does not look at where it runs and installs onto whatever system it is started on.
Take a backup or snapshot of the container before installing an add-on into a system you care about. Several uninstall routines delete data, and two of them (Coolify, Dokploy) remove every Docker container on the system.