# proxmox/pve-container architecture

> Architecture diagram of the GitHub repository proxmox/pve-container, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/proxmox/pve-container
- Repository: https://github.com/proxmox/pve-container

## Overview

This repository implements Proxmox VE container management over LXC. The documented user workflow uses `pct` to create, start, enter, stop, and destroy integer-ID containers; management is also exposed through the API. Container configuration is stored on the cluster filesystem. The tree identifies separate modules for lifecycle, snapshots, migration, setup, and backup, but no source excerpts were provided, so their internal calls and several integrations cannot be verified here.

Main entry points: [`src/PVE/LXC.pm`](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC.pm) (LXC management), [`src/PVE/LXC/Config.pm`](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Config.pm) (Container config), [`src/PVE/API2/LXC.pm`](https://github.com/proxmox/pve-container/blob/master/src/PVE/API2/LXC.pm) (Management API), [`src/PVE/LXC/Setup.pm`](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Setup.pm) (Guest setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_pct_cli["pct CLI<br/>[pct.pm]"]
  node_api["Management API<br/>[LXC.pm]"]
  node_api_config["Config API<br/>[Config.pm]"]
  node_api_status["Status API<br/>[Status.pm]"]
end

subgraph group_lifecycle["Container lifecycle"]
  node_container_runtime["LXC management<br/>[LXC.pm]"]
  node_create["Container creation<br/>[Create.pm]"]
  node_command["Container commands<br/>[Command.pm]"]
  node_cgroups["Cgroup controls<br/>[CGroup.pm]"]
  node_namespaces["Namespaces<br/>[Namespaces.pm]"]
  node_monitor["Container monitor<br/>[Monitor.pm]"]
end

subgraph group_operations["Container operations"]
  node_snapshot_api["Snapshot API<br/>[Snapshot.pm]"]
  node_migration["Migration<br/>[Migrate.pm]"]
  node_backup["Backup integration<br/>[LXC.pm]"]
  node_network_hook["Network bridge hook"]
end

subgraph group_configuration["Configuration and setup"]
  node_container_config["Container config<br/>[Config.pm]"]
  node_cluster_fs[("Cluster config files")]
  node_guest_setup["Guest setup<br/>[Setup.pm]"]
  node_setup_plugins["OS setup plugins"]
end

node_operator(("Operator"))
node_lxc_engine["LXC engine"]

node_operator -->|"runs commands"| node_pct_cli
node_pct_cli -->|"manages containers"| node_container_runtime
node_operator -->|"uses API"| node_api
node_container_config -->|"stored on"| node_cluster_fs
node_api -.->|"routes config"| node_api_config
node_api -.->|"routes status"| node_api_status
node_container_runtime -.->|"creates"| node_create
node_container_runtime -.->|"uses config"| node_container_config
node_container_runtime -.->|"dispatches"| node_command
node_container_runtime -.->|"manages limits"| node_cgroups
node_container_runtime -.->|"configures"| node_namespaces
node_container_runtime -.->|"monitors"| node_monitor
node_snapshot_api -.->|"updates snapshots"| node_container_config
node_migration -.->|"reads config"| node_container_config
node_backup -.->|"backs up"| node_container_config
node_guest_setup -.->|"selects plugin"| node_setup_plugins
node_guest_setup -.->|"configures guest"| node_create
node_container_runtime -.->|"wraps"| node_lxc_engine
node_network_hook -.->|"integrates with"| node_lxc_engine

click node_pct_cli "https://github.com/proxmox/pve-container/blob/master/src/PVE/CLI/pct.pm"
click node_api "https://github.com/proxmox/pve-container/blob/master/src/PVE/API2/LXC.pm"
click node_api_config "https://github.com/proxmox/pve-container/blob/master/src/PVE/API2/LXC/Config.pm"
click node_api_status "https://github.com/proxmox/pve-container/blob/master/src/PVE/API2/LXC/Status.pm"
click node_container_runtime "https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC.pm"
click node_container_config "https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Config.pm"
click node_create "https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Create.pm"
click node_command "https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Command.pm"
click node_cgroups "https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/CGroup.pm"
click node_namespaces "https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Namespaces.pm"
click node_monitor "https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Monitor.pm"
click node_snapshot_api "https://github.com/proxmox/pve-container/blob/master/src/PVE/API2/LXC/Snapshot.pm"
click node_migration "https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Migrate.pm"
click node_backup "https://github.com/proxmox/pve-container/blob/master/src/PVE/VZDump/LXC.pm"
click node_guest_setup "https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Setup.pm"
click node_setup_plugins "https://github.com/proxmox/pve-container/tree/master/src/PVE/LXC/Setup"
click node_network_hook "https://github.com/proxmox/pve-container/blob/master/src/lxcnetaddbr"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pct_cli,node_api,node_api_config,node_api_status toneBlue
class node_container_runtime,node_create,node_command,node_cgroups,node_namespaces,node_monitor toneAmber
class node_snapshot_api,node_migration,node_backup,node_network_hook toneMint
class node_container_config,node_cluster_fs,node_guest_setup,node_setup_plugins toneRose
class node_operator,node_lxc_engine toneIndigo
```

## Components

### User interfaces

- [pct CLI](https://github.com/proxmox/pve-container/blob/master/src/PVE/CLI/pct.pm): `src/PVE/CLI/pct.pm`
- [Management API](https://github.com/proxmox/pve-container/blob/master/src/PVE/API2/LXC.pm): `src/PVE/API2/LXC.pm`
- [Config API](https://github.com/proxmox/pve-container/blob/master/src/PVE/API2/LXC/Config.pm): `src/PVE/API2/LXC/Config.pm`
- [Status API](https://github.com/proxmox/pve-container/blob/master/src/PVE/API2/LXC/Status.pm): `src/PVE/API2/LXC/Status.pm`

### Container lifecycle

- [LXC management](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC.pm): `src/PVE/LXC.pm`
- [Container creation](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Create.pm): `src/PVE/LXC/Create.pm`
- [Container commands](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Command.pm): `src/PVE/LXC/Command.pm`
- [Cgroup controls](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/CGroup.pm): `src/PVE/LXC/CGroup.pm`
- [Namespaces](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Namespaces.pm): `src/PVE/LXC/Namespaces.pm`
- [Container monitor](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Monitor.pm): `src/PVE/LXC/Monitor.pm`

### Container operations

- [Snapshot API](https://github.com/proxmox/pve-container/blob/master/src/PVE/API2/LXC/Snapshot.pm): `src/PVE/API2/LXC/Snapshot.pm`
- [Migration](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Migrate.pm): `src/PVE/LXC/Migrate.pm`
- [Backup integration](https://github.com/proxmox/pve-container/blob/master/src/PVE/VZDump/LXC.pm): `src/PVE/VZDump/LXC.pm`
- [Network bridge hook](https://github.com/proxmox/pve-container/blob/master/src/lxcnetaddbr): `src/lxcnetaddbr`

### Configuration and setup

- [Container config](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Config.pm): `src/PVE/LXC/Config.pm`
- **Cluster config files**
- [Guest setup](https://github.com/proxmox/pve-container/blob/master/src/PVE/LXC/Setup.pm): `src/PVE/LXC/Setup.pm`
- [OS setup plugins](https://github.com/proxmox/pve-container/tree/master/src/PVE/LXC/Setup): `src/PVE/LXC/Setup`

### Other components

- **Operator**
- **LXC engine**

## Connections

- Operator → pct CLI: runs commands (evidence: `README`)
- pct CLI → LXC management: manages containers (evidence: `README`)
- Operator → Management API: uses API (evidence: `README`)
- Container config → Cluster config files: stored on (evidence: `README`)
- Management API → Config API: routes config
- Management API → Status API: routes status
- LXC management → Container creation: creates
- LXC management → Container config: uses config
- LXC management → Container commands: dispatches
- LXC management → Cgroup controls: manages limits
- LXC management → Namespaces: configures
- LXC management → Container monitor: monitors
- Snapshot API → Container config: updates snapshots
- Migration → Container config: reads config
- Backup integration → Container config: backs up
- Guest setup → OS setup plugins: selects plugin
- Guest setup → Container creation: configures guest
- LXC management → LXC engine: wraps
- Network bridge hook → LXC engine: integrates with
