Automated setup and operations for Debian control planes, servers, workstations, and Proxmox guests. infra-tools applies repeatable, machine-aware configuration over SSH, stores redacted setup state in a workspace, and provides targeted operations for hosts that are already configured.
The documentation in this checkout describes the upcoming stable v2.0.0
release. Until that tag is published, the installer’s dev channel tracks
main; use stable when you need the latest published release.
Install the launcher on the machine that will manage your hosts:
wget --timeout=20 --tries=2 -O "$HOME/.infra_tools-install.sh" https://raw.githubusercontent.com/bluehexagons/infra_tools/main/install.sh
sh "$HOME/.infra_tools-install.sh"
rm -f "$HOME/.infra_tools-install.sh"The installer needs either wget or curl; use infra-tools setup ... for
remote hosts and infra-tools upgrade to update the selected channel. The
installation guide covers prerequisites, verification,
alternate download commands, local control-plane and desktop/RDP profiles,
channels, credentials, and recovery. The documentation index
organizes detailed feature and operations guides.
Contributors should also read the contributor and coding-agent guide before changing the project.
infra-tools officially supports Debian on:
- bare-metal systems;
- virtual machines, including Proxmox-provisioned VMs; and
- unprivileged Debian LXC containers on Proxmox.
The installer and setup preflight also recognize Ubuntu and Linux Mint as best-effort Debian-compatible environments. Debian remains the only officially supported distribution.
The normal direct setup path uses --machine auto. Hosted Proxmox setup
defaults to a VM; select --machine unprivileged for the supported LXC path.
See Machine types for capability and compatibility
details.
| Area | Summary | Detailed guide |
|---|---|---|
| Setup and CLI | Unified setup, patch, shares, saved-host operations, and utility commands |
Command-line reference |
| Installation | User/system bootstrap, orchestration host prerequisites, and completion | Installation |
| Firmware | Local fwupd inventory, dependency installation, and deliberate guarded updates | Firmware |
| Control planes | Local VM/container administration tools, SSH/rsync, diagnostics, and optional coding agents | Installation, Agent systems, Quick reference |
| Servers | Security hardening, Nginx/SSL, Cloudflare tunnels, language runtimes, deployments, Gogs, and Antistatic | CLI reference, Gogs, Cloudflare tunnels, Antistatic |
| Workstations | XFCE, i3, LXQt, RDP, browsers, and desktop tooling | Workstations, XRDP, CLI reference |
| Storage | Authenticated Samba shares, private Syncthing exchange, SMB mounts, rsync sync, par2 verification, and recurring operations | Samba shares, Managed Syncthing, Storage operations |
| Deployments | Single-service deployments and infra.json multi-component manifests |
Deployments, Deployment safety, CI/CD |
| Proxmox | Host discovery, VM/LXC provisioning, lifecycle, resource stats, boot ordering, snapshots, and rolling updates | Proxmox workflows |
| Networking | Static addressing, internal HTTPS site/preview hosting, inventory, and read-only Proxmox firewall planning | Internal web, Networking |
| Sysadmin | SSH, transfers, health, services, logs, upgrades, and reachability | Sysadmin shortcuts |
Setup arguments are saved without passwords, reconstructed commands redact secrets, and workspace credential files use restrictive permissions. Deployments keep persistent application state outside release directories and create verified backups where required. Read Deployment safety for rollback and recovery behavior.
Steps detect the target machine type and skip capabilities that cannot safely run in containers. Kernel, firewall, and desktop behavior is therefore capability-aware rather than assumed. See Machine types.
The security profile hardens SSH, the firewall, package updates, journald, fail2ban, and service boundaries. Samba uses authenticated SMB3+, signing and encryption, TCP 445 only, and validated configuration reloads. See the Samba guide and maintenance guide.
Automatic APT updates remain enabled, while language ecosystem upgrades and release selection use conservative freshness and opt-in policies. Cleanup uses bounded cache, log, journal, and temporary-artifact policies and purges packages APT marks unused, including superseded kernels. It expires recognized crash reports and returns unused filesystem blocks to supported physical, virtual, and Proxmox storage, then checks block and inode pressure across local mounts. See the recurring maintenance guide.
Use patch for general saved-configuration changes. Use a feature-specific
fast path when available—for example, infra-tools shares HOST updates Samba
users, access, paths, and share declarations without running unrelated setup
work. See Saved configuration operations.
# Inspect a saved host
infra-tools list
infra-tools info example.com
# Apply a targeted general patch
infra-tools patch example.com admin --ssl
# Update Samba shares only
infra-tools shares fileserver \
--share write documents /srv/documents alice,bob
# Inspect and manage a Proxmox VM by its saved local name
infra-tools vm health agent-dev-01
infra-tools vm stats agent-dev-01
infra-tools vm autostart agent-dev-01
# Audit local firmware and explicitly apply available updates
infra-tools firmware audit
infra-tools firmware updateUse the documentation index for the complete command and feature map.
Run the default checks from a checkout. This includes building a wheel in a temporary directory, installing it into an isolated virtual environment, and smoke-testing both installed launchers outside the source tree:
make check
./run_tests.py --suite smokeRoutine continuous integration runs the suite in Debian Trixie on Python 3.13, the interpreter shipped by that release. Version-tagged releases additionally run the suite on the minimum supported Python version (3.10) and the latest Python 3 version in the release policy (3.14). Expensive live tests remain opt-in.
See Saved configuration operations for test selectors and Proxmox workflows for live-host notes.
Apache License 2.0