How to Create a Proxmox Offline Repository Mirror for Air-Gapped Environments

Running your own package mirror (such as for Proxmox products) may seem like an advanced setup, but it addresses challenges that are increasingly relevant in modern infrastructures. At its core, a mirror is simply a local copy of selected repositories, yet the advantages extend far beyond faster downloads. By keeping a local mirror, organizations can reduce external bandwidth usage because every server pulls packages from the same local source rather than repeatedly accessing the internet. This also ensures consistency across nodes, avoiding scenarios where some machines install slightly newer or different packages than others, which can lead to unpredictable behavior. Additionally, relying on a local mirror provides controlled availability; even if an external repository is temporarily down, your systems remain unaffected.

Security and compliance also benefit from a local mirror. Administrators can control which repositories and signing keys are trusted, reducing exposure to tampered or malicious sources. Snapshots of the repository can be frozen at specific points in time, allowing updates to be tested in staging environments before being deployed, creating an auditable and predictable update process. This also brings in some additional features, such like staging of packages from a synced repository which might come close to the enterprise repositories of Proxmox.

The importance of mirrors becomes even more pronounced in air-gapped environments, where systems have no direct access to the internet or public repositories. In such scenarios, a local mirror becomes the only source of packages and updates. Without it, administrators would be forced to manually transfer packages from external machines, risking inconsistency, human error, or outdated software. A well-maintained mirror in an air-gapped network ensures that updates, security patches, and dependencies are reliably available while preserving the isolation of the environment. Within this HowTo, we will now setup a mirror for the Proxmox non-enterprise / no-subscription repositories and serve them internally on our own domain and webserver with nginx.

Table of Content

Installation

The proxmox-offline-mirror package is a tool provided exclusively through the official Proxmox VE (PVE) repository. It allows users to create offline mirrors of Proxmox and Debian repositories, which is especially useful in air-gapped environments or when bandwidth limitations make online updates impractical.

There are two main ways to install the package: directly on a Proxmox VE node, or on a Debian system by adding the PVE repository. The recommended approach is to use a Debian 13 (Trixie) system, which ensures compatibility and avoids conflicts with other repositories.

Adding the Proxmox Repository

/etc/apt/sources.list.d/proxmox.sources

which contains the following content:

Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg

This configuration points your system to the Proxmox repository without requiring a subscription, and ensures package integrity with the provided GPG key.

Afterwards, we can simply update the repository data and install the package proxmox-offline-mirror by running the following commands:

apt-get update ; apt install proxmox-offline-mirror

Once installed, the proxmox-offline-mirror command will be available on your system, ready to create offline mirrors for Proxmox VE and Debian repositories.

This method allows you to prepare air-gapped environments efficiently or maintain local mirrors for multiple Proxmox installations. The next step is to prepare the directory structure for the mirrored repositories which can be placed anywhere. In this example, we use /var/lib/proxmox-offline-mirror/mirrors and mirror the following repositories (you can add or remove these as needed):

  o debian-trixie-security
  o pve-no-subscription

The directories can simply be created this way:

mkdir -p /var/lib/proxmox-offline-mirror/mirrors/.pool
mkdir -p /var/lib/proxmox-offline-mirror/mirrors/debian-trixie-security
mkdir -p /var/lib/proxmox-offline-mirror/mirrors/pve-no-subscription

Configuration

One of the most important parts is to configure the /etc/proxmox-offline-mirror.cfg file, which holds the information of the mirrored repositories. This file allows us to mirror Debian based repositories in general, which can be a Debian upstream repository, but also the Proxmox pve-no-subscription repository. In case of a fully air-gapped environment, both may make sense to have in place and an example configuration could look like:

mirror: debian-trixie-security
        architectures amd64
        architectures all
        base-dir /var/lib/proxmox-offline-mirror/mirrors
        ignore-errors false
        key-path /usr/share/keyrings/debian-archive-trixie-security-automatic.gpg
        repository deb http://security.debian.org/debian-security trixie-security main contrib non-free non-free-firmware
        skip-sections games
        skip-sections debug
        skip-sections graphics
        skip-sections GNOME
        skip-sections KDE
        sync true
        verify true

mirror: pve-no-subscription
        architectures amd64
        architectures all
        base-dir /var/lib/proxmox-offline-mirror/mirrors
        ignore-errors false
        key-path /usr/share/keyrings/proxmox-archive-keyring.gpg
        repository deb http://download.proxmox.com/debian/pve trixie pve-no-subscription
        sync true
        verify true

Make sure to copy over and include the GPG files and to adjust the key-paths.

Mirroring Repositories

After creating the configuration file of the mirrored repositories, we finally need to mirror and snapshot them.

proxmox-offline-mirror mirror snapshot create debian-trixie-security
proxmox-offline-mirror mirror snapshot create pve-no-subscription

This creates a directory below our recently created directory /var/lib/proxmox-offline-mirror/mirrors/ including a timestamp such as 2025-08-26T19:43:34Z.

Hint: To make overall node management easier and to avoid adjusting paths for each snapshot, you might simply create a symlink like latest and point it to the most recent snapshot.

Proxy Connection

proxmox-offline-mirror supports the use of HTTP or HTTPS proxies through environment variables, which makes it possible to operate in restricted network environments where direct internet access is not available. The tool relies on the environment variable ALL_PROXY to determine whether requests should be routed through a proxy.

When ALL_PROXY is set, all HTTP and HTTPS connections are routed through the specified HTTP proxy. At the moment, only HTTP proxies are supported. The proxy address must follow the format [http://][user:password@]<host>[:port]. If no port is specified, the default value of 1080 is used.

For example, to use a proxy server at proxy.example.com on port 8080 with authentication credentials, you can export the variable like this:

export ALL_PROXY=http://myuser:mypassword@proxy.example.com:8080

With this configuration, all connections made by proxmox-offline-mirror will be routed through the specified proxy server.

APT Web Repository with Nginx

Afterwards, we can expose the staged repositories by making them accessible via HTTP or HTTPS through a webserver. In this case, we use nginx. Since we are only serving static content, the mirrored repositories can simply be linked into the default web root directory.

apt-get -y install nginx
ln -s /var/lib/proxmox-offline-mirror/mirrors/ /var/www/html/mirror

The whole root directory containing all mirrored snapshots is now linked and can be accessed by remote clients via HTTP or HTTPS.

PVE Nodes Adding the Air-Gapped Repository

As the final step, we need to make sure that our Proxmox VE nodes use the newly created repository mirror. Depending on which repositories are mirrored, we need to adjust the apt sources accordingly. In this example, we modify only the Proxmox sources in /etc/apt/sources.list.d/proxmox.sources.

Types: deb
URIs: http://repo-pve.gyptazy.com/mirrors/pve-no-subscription/latest
Suites: trixie
Components: pve-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg

Afterwards, we can update our sources including our self-mirrored Proxmox repository:

apt-get update

After updating the repository, the air-gapped environment can be used by Proxmox VE nodes which now consumes our offline mirrored repository.

Conclusion

Creating an air-gapped offline repository mirror for Proxmox VE is surprisingly straightforward and can be accomplished quickly using the proxmox-offline-mirror tool. By following the steps outlined in this guide, organizations can ensure that their Proxmox nodes have a reliable, consistent, and secure source of packages and updates, even in environments with no internet access.

From a business perspective, enterprises are strongly encouraged to obtain an official subscription. This ensures access to enterprise repositories and supports the ongoing development of Proxmox VE. Until offline mirroring access is expanded further, this guide provides a practical and effective solution for non-enterprise environments.

Such setups work best when fully automated. In this context, my Ansible modules for Proxmox can help automate storage integration, subscription handling, and even cluster creation. This guide is intended for Proxmox VE administrators operating in restricted or air-gapped environments who need a reliable, secure, and reproducible way to manage package updates without direct internet access.