Community Scripts — Core

The shared shell engine behind the community-scripts projects
Container and VM builds for Proxmox VE and Incus, from one codebase

---

What is this?

The engine, not the scripts.

This repository holds the shared Bash libraries that every community script runs on: argument parsing, the whiptail wizard, container and VM creation, the in-container installer, error handling, telemetry and the helper library.

You do not run anything from here directly. Application scripts live in the script repositories and source this engine at start-up.

The engine detects the host at runtime and loads the matching backend, so a single ct/ script works on both Proxmox VE and Incus — there is no separate Incus script tree.

---

Status

The split is in progress. Extracting the engine is done, but the script repositories have not been moved over yet:

Repository	Scripts bootstrapping from core
ProxmoxVED	1 of 95 (ct/debian.sh, the pilot)
ProxmoxVE	0 of 577 — untouched, still ships and loads its own misc/

Everything else still sources its own in-repo misc/build.func. So the fork and branch workflow described below works today only for the converted scripts; pointing COMMUNITY_SCRIPTS_CORE_URL at a fork has no effect on a script that never loads core in the first place.

ProxmoxVE stays untouched until the mechanism is proven in ProxmoxVED. See Divergence from ProxmoxVE for what has to be ported before it can move.

---

Repository map

Repository	Contains
core (this repo)	The engine — shared/, pve/, incus/
ProxmoxVE	Application scripts — ct/, install/, vm/, json/, and tools/pve/
ProxmoxVED	Where new scripts are tested before they move to ProxmoxVE
Incus	Incus host tooling and documentation

---

Layout

shared/ platform-agnostic engine
build.func entry point, origin resolution, platform dispatch
build-ui.func whiptail wizard entry point (loader)
build-ui/validate.func container id, hostname, network, IP range validators
build-ui/defaults.func storage selection, .vars files, app defaults
build-ui/advanced.func the advanced settings wizard
build-ui/menu.func settings and diagnostics menus, install_script, start
core.func colors, spinners, messaging, silent()
tools.func helper library used by install scripts (loader)
tools/system.func packages, repositories, OS probes, services
tools/forge.func GitHub, GitLab and Codeberg releases
tools/runtime.func language runtimes and application installers
tools/db.func databases and search engines
tools/hwaccel.func GPU detection and hardware acceleration
install.func in-container bootstrap (multi-distro)
alpine-install.func in-container bootstrap for Alpine
alpine-tools.func helper library for Alpine
api.func telemetry reporting
error_handler.func traps, diagnostics, exit codes
preflight.func host readiness checks
cloud-init.func cloud-init generation for VMs
lxc-platform.func host detection (Proxmox VE / Incus / in-container)
source-origin.func git remote → raw content base
pve/ Proxmox VE backend
backend.func container creation via pct
vm-core.func VM creation via qm
vm-app.func VM application provisioning
incus/ Incus backend
build.func entry hooks over the shared wizard
backend.func container creation via the incus CLI
core.func messaging and compatibility layer
tools.func Incus-side helper wrappers
vm-core.func VM creation on Incus
headers/ figlet banners, generated from the script repos
<type>/ ct, addon, vm, tools — the banner for both platforms
<type>/pve/ only when that script exists on Proxmox VE alone
<type>/incus/ only when that script exists on Incus alone
tools/ developer helpers (run.sh)
images/ logos used in container MOTD and VM output

Why headers live here

A header is a figlet banner derived from a script's APP= line — a generated artifact, never hand-written. The same banner renders on both platforms, so keeping a copy in every script repo was pure duplication. .github/workflows/generate-headers.yml walks ProxmoxVE, ProxmoxVED and Incus every six hours (or immediately on a scripts-changed dispatch) and regenerates the tree.

They are keyed by APP_TYPE, not by the folder a script lives in — scripts under tools/addon/ declare APP_TYPE="addon".

The platform subfolder is optional and applies to every type. Most scripts run on both hosts and their banner sits flat under the type. A script that exists on one platform only — host tools today, Incus VMs or a host-touching add-on tomorrow — gets a pve/ or incus/ subfolder, and the generator decides that purely from a pve/ or incus/ segment in the script's path. So a repo opts in by where it puts the script, with no engine change and no new variable.

get_header() tries the platform folder first and falls back to the flat one, which means an Incus-only VM script will be picked up automatically the day it lands in vm/incus/. A newly merged script has no banner until the generator has run; header_info() prints nothing in that case rather than failing.

---

How loading works

The engine and the scripts live in different repositories, so both are resolved independently. A CT script bootstraps the engine, and everything after that goes through the resolver in shared/build.func:

Path prefix	Resolves against	Example
shared/, pve/, incus/	engine root	pve/backend.func → core/pve/backend.func
everything else	scripts root	install/debian-install.sh → ProxmoxVE/install/debian-install.sh

Paths are folder-qualified, so the prefix alone decides the root and there is no name-to-folder map to keep in sync. It is also what lets the backend files drop their platform prefix: incus/build.func and shared/build.func can coexist because nothing resolves by basename.

Resolution order

1. Local checkout — used when found, so development needs no network at all
2. Git origin — a checkout's own remote and branch become its raw base, so a fork or branch is picked up automatically
3. Defaults — community-scripts/core@main for the engine, community-scripts/ProxmoxVED@main for the scripts

Environment variables

Variable	Root	Purpose
COMMUNITY_SCRIPTS_CORE_DIR	engine	Local core checkout
COMMUNITY_SCRIPTS_CORE_URL	engine	Raw base for the engine
COMMUNITY_SCRIPTS_ROOT	scripts	Local script-repo checkout
COMMUNITY_SCRIPTS_URL	scripts	Raw base for the scripts
COMMUNITY_SCRIPTS_DIR	engine	Back-compat alias for …_CORE_DIR
COMMUNITY_SCRIPTS_STATE_DIR	—	Defaults, diagnostics and build logs
LXC_PLATFORM	—	Force pve, incus, incus-container or container (debugging)

---

Testing a fork or branch

Because the two roots are independent, either side can be swapped without touching the other. This is what makes fork-based development work.

Local checkouts — clone core next to the script repo and just run a script. No configuration, no network:

git clone https://github.com/YOU/core
git clone https://github.com/YOU/ProxmoxVE
cd ProxmoxVE && bash ct/debian.sh

Each checkout's git remote and branch become its raw base automatically, so a container built this way pulls the rest from your fork, not from upstream.

Remote fork, engine only — production scripts against your core branch:

export COMMUNITY_SCRIPTS_CORE_URL=https://raw.githubusercontent.com/YOU/core/my-branch
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"

Remote fork, both sides — see tools/run.sh:

curl -fsSL https://raw.githubusercontent.com/community-scripts/core/main/tools/run.sh |
bash -s -- https://raw.githubusercontent.com/YOU/ProxmoxVE/my-branch ct/debian.sh \
https://raw.githubusercontent.com/YOU/core/my-branch

---

Platform detection

Environment	Detected by	Backend
Proxmox VE host	pveversion present	pve/backend.func
Incus host	incus CLI and a reachable daemon	incus/build.func
Inside an Incus container	/dev/incus/sock or the Community Scripts MOTD	update mode

Override with LXC_PLATFORM when debugging.

Host tools are the one thing that cannot be shared: tools/pve/ scripts call pve* binaries, and their Incus counterparts live in the Incus repository.

---

Contributing

Engine changes affect every script in the collection at once, so they get more scrutiny than an application script.

I want to…	Go here
Change the engine	Open a PR here, and say which platforms you tested on
Add or fix an application script	ProxmoxVED for new ones, ProxmoxVE for fixes
Add Incus host tooling	Incus
Report a bug	Issues — include your host platform and whether it reproduces on the other one
Ask a question	Discord

Before opening a PR:

• Test on both backends when you touch shared/. A change that only works on Proxmox VE belongs in pve/.
• Never hardcode a raw URL. Use _cs_source_func "shared/<name>.func" (or pve/…, incus/…) so both roots keep resolving and forks keep working.
• shared/tools.func and shared/build-ui.func are loaders. Source those, not the parts under shared/tools/ or shared/build-ui/. If you add or rename a function, regenerate the matching API.txt in the same PR — CI compares against it.
• New files go in the folder that matches their root. Nothing resolves by basename, so incus/tools.func and shared/tools.func are both fine.
• shellcheck and shfmt the files you touched.

---

Divergence from ProxmoxVE

The engine here comes from the ProxmoxVED lineage. Production ProxmoxVE still ships its own misc/*.func and has drifted in a few places. Nothing below is broken today — ProxmoxVE loads its own copy — but each item is a regression waiting to happen when ProxmoxVE is folded onto this repo.

Missing here, must be ported first:configure_http_proxy and the var_http_proxy / var_http_no_proxy chain · var_inherit_host_ca · var_github_token · nginx_enable_site() · get_php_fpm_socket() (19 ProxmoxVE install scripts call it) · the _bootstrap_die / _bootstrap_source download hardening.

Behaviour differences to reconcile:silent() ends with exit here but return in ProxmoxVE, so a caller cannot handle its own failure · apt_update_safe is called by ensure_whiptail but never defined here, which silently skips an apt-get update.

Already ahead here — do not regress when merging: the multi-distro install.func · the whole Incus backend and platform split · setup_cloud_init_network_no_rename · telemetry platform reporting.

---

License

MIT — free to use, modify and redistribute. See LICENSE.

---

_{Built on the foundation of tteck's original work · In memory of tteck
Proxmox® is a registered trademark of Proxmox Server Solutions GmbH. Incus is a project of LinuxContainers.}