Incus App Launcher for Proxmox Community Scripts

Run community-scripts/ProxmoxVE apps on Incus. incus-app-launcher is a thin Incus-native wrapper that fetches upstream Proxmox community scripts on demand, creates Incus LXC containers, and runs self-hosted app installers and addon scripts without forking the upstream catalog.

Common search phrases this project targets:

• Proxmox community scripts on Incus
• Incus app launcher
• Incus LXC app installer
• self-hosted apps on Incus
• run Proxmox VE helper scripts with Incus

The launcher stays thin. It does not fork the upstream app catalog or embed large upstream installers in this repo. Instead, it fetches:

• ct/<app>.sh
• install/<app>-install.sh
• shared helper files

from the upstream repo at a chosen ref, then:

1. Reads the upstream container defaults.
2. Creates an Incus container with similar limits.
3. Bootstraps a small base package set inside the guest.
4. Pushes the upstream installer into the guest.
5. Applies a small automation profile when the launcher knows how to answer upstream prompts.

What This Project Does

incus-app-launcher bridges two ecosystems:

• upstream Proxmox community app installers
• local Incus containers and addon execution

In practice, that means you can use the upstream app definitions from community-scripts/ProxmoxVE while deploying to Incus instead of Proxmox VE. The goal is not to replace the upstream project. The goal is to make those app installers usable from an Incus-first workflow with minimal translation logic.

Why People Find This Repo

Common discovery questions this README should answer:

• Can I run Proxmox community scripts on Incus?
• Is there an Incus alternative to Proxmox VE helper scripts?
• How do I deploy self-hosted apps to Incus from the community-scripts catalog?
• Can I run upstream addon scripts like Dockge inside an existing Incus container?

The answer is yes, within the scope of the upstream scripts and the launcher's current Incus compatibility layer.

Status

This project is usable, but still early.

What exists today:

• generic create flow for upstream apps
• generic addon flow for upstream tools/addon/*.sh scripts inside existing containers
• optional PocketBase metadata enrichment for discovery and script labeling
• prompt detection for upstream installers
• a small set of automation profiles for interactive apps
• dry-run and smoke-test commands
• real-world validation on an Incus VPS

What does not exist yet:

• broad compatibility guarantees across the full upstream app catalog
• complete translation of Proxmox-specific features
• a mature release process

Support Model

• Any upstream app can be attempted.
• The local maintained list is only for launcher automation profiles, not for a master allowlist of compatible apps.
• Unprofiled apps use the generic flow and empty stdin unless prompt handling is added.
• If an app fails, the first preference is improving generic Incus behavior. App-specific profiles should stay small and focused.

Automation Profiles

• adguard
• vaultwarden
• netbird

Tested Apps

Validated on a real Incus 6.21 host:

• adguard
• docker
• netbird
• dockge via addon install dockge inside a Docker-capable target container

Quick Start

List the apps with launcher automation profiles:

./bin/incus-app list-supported

Inspect an upstream app before creating an Incus container:

./bin/incus-app show adguard --ref main

Create an Incus container from an upstream Proxmox community script:

./bin/incus-app create adguard --name adguard --ref main

Run an upstream addon script inside an existing Incus container:

./bin/incus-app addon install dockge --target docker-host --prompt-mode interactive

Requirements

• bash
• curl
• awk
• sed
• mktemp
• incus

Optional for metadata search/enrichment:

• jq

Safety Notes

• The launcher uses the existing default Incus profile unless you change the code or environment around it.
• It does not modify host-wide Incus profiles, networks, or storage pools.
• Per-instance root disk sizing is done through instance device override, not by editing shared profiles.
• --cleanup-on-failure only removes a newly created instance when the launcher itself fails after creation. Successful runs leave the instance in place.

Usage

list-profiled is an alias:

./bin/incus-app list-profiled

Show the upstream defaults and launcher notes for an app:

./bin/incus-app show netbird --ref main

show also scans the fetched installer for common prompt patterns and reports whether upstream interactivity appears to be present.

Search script metadata from PocketBase:

./bin/incus-app search dockge

Show an unprofiled app and inspect prompt hints:

./bin/incus-app show pihole --ref main

Create an app container:

./bin/incus-app create netbird --name netbird --ref main

Run upstream prompts interactively in your terminal:

./bin/incus-app create docker --name docker-test --prompt-mode interactive

Run an upstream addon script inside an existing container:

./bin/incus-app addon install dockge --target docker-host --prompt-mode interactive

Run an addon update flow inside an existing container:

./bin/incus-app addon update dockge --target docker-host --prompt-mode interactive

Delete the instance automatically if creation fails:

./bin/incus-app create netbird --name netbird --cleanup-on-failure

Run a basic smoke test after creation:

./bin/incus-app smoke-test adguard --name adguard-smoke --cleanup-on-failure

Pin to a specific upstream commit:

./bin/incus-app create adguard \
  --name adguard \
  --ref 4a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8g9

Print the Incus commands without executing them:

./bin/incus-app create vaultwarden --name vaultwarden --dry-run

Override the upstream repo source, useful for local development:

UPSTREAM_REPO="file:///home/jon/Dev/github/ProxmoxVE" \
  ./bin/incus-app show adguard

Notes

• Upstream has two relevant models:
  • app containers driven by ct/<app>.sh plus install/<app>-install.sh
  • addon scripts driven by tools/addon/<name>.sh
• Addons are meant to run inside an existing target container, not through the normal app-creation path.
• dockge is the current example of an upstream addon-oriented workflow.
• PocketBase metadata is used only to enrich discovery and classification. Execution still relies on the upstream scripts.
• PocketBase metadata can identify:
  • script type (lxc, vm, addon, pve)
  • development status (ProxmoxVED vs ProxmoxVE)
  • disabled/deleted state
• Public repo hardening includes CI for syntax and dry-run smoke coverage.
• netbird is interactive upstream. The launcher answers the prompts with: managed deployment and "skip connection for now".
• Prompt modes:
  • profile: use launcher-provided answers when a profile exists
  • empty: feed empty stdin
  • interactive: attach upstream prompts to the current terminal
• Addon commands support interactive and empty prompt modes.
• Some upstream scripts still assume a Proxmox environment. Unprofiled apps are attempted with empty stdin and may still need manual fixes or more launcher automation.
• The launcher defaults to main if --ref is not set, but using a pinned commit is recommended for repeatable builds.
• The MVP uses your existing Incus default profile and network. Custom network selection is not automated yet.

SEO Summary

This repository is an Incus launcher for the Proxmox community scripts catalog. It helps users run upstream LXC app installers and addon scripts on Incus, especially for self-hosted services such as AdGuard, Vaultwarden, NetBird, Docker, and Dockge, without maintaining a forked copy of the upstream app catalog.