LXC AutoScale

LXC AutoScale is an async resource management daemon for Proxmox environments. It automatically adjusts CPU and memory allocations for LXC containers based on real-time usage metrics and predefined thresholds. It supports local execution, remote execution via SSH, or the Proxmox REST API as backend. Container cloning (horizontal scaling) is also supported as an experimental feature.

• v2.0 — async architecture, Pydantic config, dual CLI/API backend, security hardening
• Tested with Proxmox 8.x (8.3.3+)

Quick Start

Method	Instructions
Docker	Docker
No Docker	Install script

Features

• Async architecture — fully non-blocking event loop using asyncio
• Dual backend: CLI (pct commands) or Proxmox REST API (proxmoxer)
• Pydantic configuration with type validation and ${ENV_VAR} expansion for secrets
• Automatic vertical scaling of CPU cores and memory based on usage thresholds
• Horizontal scaling via container cloning (experimental)
• Per-container or per-group threshold configuration using tiers
• CPU core pinning for Intel hybrid CPUs (Alder Lake+): pin containers to P-cores or E-cores
• Cgroup-based metrics for both CPU and memory (no pct exec needed)
• Timezone-aware off-peak scheduling (configurable, defaults to UTC)
• Host CPU and memory reservation to prevent over-allocation
• Container exclusion list (ignore_lxc)
• Energy efficiency mode that reduces resources during off-peak hours
• SSH connection pool with configurable host key verification (default: reject)
• Secret masking in log output (passwords, tokens, API keys redacted)
• Notifications via email (SMTP), Gotify, and Uptime Kuma (async, fire-and-forget)
• JSON metrics log with rotation (10MB limit)
• Local execution, remote execution via SSH, or REST API
• Docker support with optional non-root user for API-only mode
• 370 tests with 87% code coverage
• Boost/revert scaling mode — temporary resource boosts with automatic revert after configurable duration

Note

If you need to autoscale Virtual Machine resources on Proxmox hosts, you will like this project.

Quick Start

Prerequisites

• Proxmox VE 7.x or 8.x (tested with 8.3.3)
• Python 3.9+
• Root access to the Proxmox host
• LXC containers already created and configured
• Internet connection for downloading the installation script

Installation

curl -sSL https://raw.githubusercontent.com/fabriziosalmi/proxmox-lxc-autoscale/main/install.sh | bash

Tip

Once installed, verify the service is running:

systemctl status lxc_autoscale.service

CPU Measurement

Starting with v1.2.0, CPU usage is measured via host-side cgroup accounting (cgroup v2/v1). This reads the kernel's own CPU time tracking for each container directly from the Proxmox host, without needing to execute commands inside containers. Benefits:

• Accurate measurements that match what Proxmox shows in its web UI
• No dependency on LXCFS being installed in containers
• Minimal overhead (simple file reads instead of pct exec per container)
• Works correctly on low-core hosts with many containers

If cgroup accounting is unavailable, the daemon falls back to /proc/stat (requires LXCFS) and then to load average estimation.

LXCFS Configuration (optional, for fallback method)

If you want the /proc/stat fallback to work correctly, configure LXCFS with the -l flag in /lib/systemd/system/lxcfs.service:

ExecStart=/usr/bin/lxcfs /var/lib/lxcfs -l

Then run systemctl daemon-reload && systemctl restart lxcfs and restart your containers.

See the Proxmox forum thread for details.

CPU Core Pinning (Intel Big.LITTLE)

On hybrid Intel CPUs (Alder Lake / Raptor Lake / Arrow Lake, 12th gen+), you can pin containers to Performance or Efficiency cores via the cpu_pinning tier setting:

TIER_databases:
  lxc_containers:
    - "102"
  cpu_pinning: p-cores       # Run on Performance cores only

TIER_background_tasks:
  lxc_containers:
    - "105"
    - "106"
  cpu_pinning: e-cores       # Run on Efficiency cores only

Accepted values: p-cores, e-cores, all, or an explicit range like 0-11 or 0,2,4,6-8. Core topology is auto-detected from the kernel at startup.

Configuration

LXC AutoScale is configured via a YAML file at /etc/lxc_autoscale/lxc_autoscale.yaml. For detailed configuration options, see the documentation.

Tip

If you need LXC AutoScale configuration for all your LXC containers, you can automatically generate it by running this command:

curl -sSL https://raw.githubusercontent.com/fabriziosalmi/proxmox-lxc-autoscale/main/lxc_autoscale/lxc_autoscale_autoconf.sh | bash

Additional Resources

• LXC AutoScale UI - Simple web UI to check scaling actions and logs
• LXC AutoScale - TIER snippets for 40 self-hosted apps

Tip

LXC AutoScale ML has been moved to a separate repository.

Frequently Asked Questions

Can I use this on Proxmox 7.x?

LXC AutoScale is tested on Proxmox VE 8.3.3. It may work on older versions, but compatibility is not guaranteed.

Will this work with my existing containers?

Yes. Configure the container IDs in the YAML file and the service will start managing them.

Does this support virtual machines (VMs)?

No, LXC AutoScale is designed for LXC containers only. For VM autoscaling, see proxmox-vm-autoscale.

Can I run this remotely?

Yes. Two options:

1. SSH (default): Set use_remote_proxmox: true and provide SSH credentials.
2. REST API (v2.0): Set backend: api and configure proxmox_api with API tokens. Requires pip install proxmoxer.

Can I use the Proxmox REST API instead of SSH?

Yes (v2.0+). Set backend: api in the YAML config and provide API token credentials under proxmox_api. This avoids SSH entirely and uses scoped API tokens instead of root shell access. See the configuration docs for details.

Is it safe to use in production?

LXC AutoScale backs up container settings before making changes and supports rollback via --rollback. Test thoroughly in a non-production environment before deploying to production.

How often does it check container resources?

The default polling interval is 300 seconds (5 minutes). Adjust with the poll_interval setting.

Can I exclude certain containers from autoscaling?

Yes. Add container IDs to the ignore_lxc list in the configuration file.

For more detailed questions and answers, see the Q&A documentation.

Contributing

Contributions are welcome. To get involved:

• Open an issue to report bugs or request features.
• Submit a pull request.
• Fork the repository to develop custom features.

Contributors

LXC AutoScale is made better by the people who contribute to it. Thank you to everyone who has helped improve the project.

• Fabrizio Salmi — Project author and maintainer
• Clement Kibet

See the full contributors graph.

Disclaimer

Caution

The author assumes no responsibility for any damage or issues that may arise from using this tool.

License

LXC AutoScale is licensed under the MIT License, which means you are free to use, modify, and distribute this software with proper attribution. For more details, please see the LICENSE file.