Automation Platform for Homelab Infrastructure
Provision VMs, manage certificates, orchestrate Ansible playbooks, build SLB configurations on A10 vThunders, and monitor it all from a single web interface.
Perimeter is a self-hosted automation platform built for homelab and small infrastructure environments. It provides a unified web UI for:
- VM Provisioning — Clone Proxmox templates via Terraform with cloud-init. Supports Linux, VyOS, and A10 vThunder ACOS.
- Ansible Orchestration — Run playbooks against your inventory directly from the browser.
- Certificate Management — Issue and renew Let's Encrypt certificates via Certbot, deploy to Linux hosts or A10 vThunders.
- DNS Management — Create and manage local DNS records via Pi-hole v6 API.
- IPAM — Track IP address allocations in Netbox.
- vThunder SLB Manager — Build and tear down VIPs, service groups, health monitors, and SSL templates on A10 load balancers via aXAPI.
- Template Refresh — Automated template maintenance: clone, boot, update, clean, re-template.
- Monitoring — Prometheus
/metricsendpoint with a pre-built Grafana dashboard.
Every feature is modular — enable only what you need via environment variables. No feature dependencies; disable DNS, IPAM, or vThunder management without affecting core VM operations.
Mission Control Dashboard — Icon rail navigation, VM orchestration panel with live Proxmox VMID badges, persistent assets table with health status

Fleet Deployment & Template Management — Quick Fleet builder with preview table, Proxmox template management flyout with refresh controls, live terminal streaming

Ansible Orchestration — Playbook selection with YAML viewer, inventory group targeting, live execution output with syntax highlighting

- A Proxmox VE cluster (8.x or 9.x) with API access
- A Rocky Linux 9, RHEL 9, Ubuntu 22.04+, or Debian 12+ server to run Perimeter
- VM templates in Proxmox with cloud-init and QEMU guest agent enabled
curl -fsSL https://raw.githubusercontent.com/valowmfk/perimeter/main/installer/install.sh | sudo bashThe installer will:
- Install system dependencies (Python, Terraform, Ansible, SOPS, Age)
- Clone the repository to
/opt/perimeter/ - Launch an interactive setup wizard
The setup wizard guides you through:
- Service user creation
- Feature selection (choose which modules to enable)
- Proxmox API token creation (automatic)
- Network/subnet configuration
- SSH key generation
- Credential collection for enabled features
- Secret encryption with SOPS + Age
- Systemd service installation
git clone https://github.com/valowmfk/perimeter.git /opt/perimeter
cd /opt/perimeter
pip3 install -r requirements.txt
sudo python3 installer/setup.py --install-dir /opt/perimetercd /opt/perimeter
sudo bash installer/upgrade.shThe upgrade script will:
- Pull the latest code from git
- Update Python dependencies
- Re-initialize Terraform providers
- Restart the
perimeterandperimeter-workerservices - Run a health check against the
/api/versionendpoint
If upgrading from v3.1, the worker service file may need to be regenerated. The script will prompt you if this is needed.
Perimeter (Flask)
├── Web UI (single-page app)
│ ├── VM Provisioning drawer
│ ├── Ansible Orchestration drawer
│ ├── Certificate Management drawer
│ ├── DNS Management drawer
│ ├── IPAM drawer
│ └── vThunder SLB Manager drawer
│
├── Backend (Flask blueprints)
│ ├── core_bp — UI serving (always on)
│ ├── vms_bp — VM lifecycle (always on)
│ ├── network_bp — Subnet/DNS API (always on)
│ ├── playbooks_bp — Ansible execution (toggleable)
│ ├── certificates_bp — Cert management (toggleable)
│ └── system_bp — vThunder/Proxmox (toggleable)
│
├── Workflows (subprocess workers)
│ ├── provision_linux.py
│ ├── provision_vthunder.py
│ ├── provision_vyos.py
│ ├── bootstrap_linux.py
│ ├── bootstrap_vthunder.py
│ ├── destroy_vm.py
│ └── refresh_template.py
│
├── Terraform (IaC)
│ ├── modules/linux_vm
│ ├── modules/vthunder_vm
│ └── modules/vyos_vm
│
└── Integrations
├── Proxmox API (VM management)
├── A10 aXAPI v3 (vThunder configuration)
├── Pi-hole v6 API (DNS records)
├── Netbox API (IPAM tracking)
├── Loki (audit logging)
└── Prometheus (metrics)
Every optional module can be enabled or disabled via environment variables:
| Variable | Default | Module |
|---|---|---|
PERIMETER_FEATURE_ANSIBLE |
1 |
Ansible Orchestration |
PERIMETER_FEATURE_CERTS |
1 |
Certificate Management |
PERIMETER_FEATURE_DNS |
1 |
DNS Management (Pi-hole) |
PERIMETER_FEATURE_IPAM |
1 |
IPAM (Netbox) |
PERIMETER_FEATURE_VTHUNDER |
1 |
vThunder SLB Manager |
PERIMETER_FEATURE_AUDIT |
1 |
Audit Logging (Loki) |
Set to 0 to disable. Features are set in the systemd service file or as environment variables.
When a feature is disabled:
- Its Flask blueprint is not registered (no API routes)
- Its UI drawer is not rendered (no HTML sent to browser)
- Its JavaScript module is not initialized
- Provision workflows skip DNS/IPAM steps gracefully
All sensitive configuration is encrypted with SOPS + Age. The installer handles key generation and encryption automatically.
Secrets are stored in secrets/perimeter.enc.env and decrypted at runtime by the application.
Multiple subnets are supported. Configure in python/config.py:
SUBNETS = {
"10.1.55.0/24": {"gateway": "10.1.55.254", "dns": ["10.1.55.10", "10.1.55.11"]},
"10.255.0.0/24": {"gateway": "10.255.0.1", "dns": ["10.1.55.10", "10.1.55.11"]},
}The UI provides a subnet dropdown during VM creation, with IP validation against the selected subnet.
Perimeter auto-discovers templates from Proxmox. Templates are routed by naming convention:
| Template prefix | Workflow | Resources |
|---|---|---|
acos* |
vThunder | Template-defined (fixed) |
vyos* |
VyOS | Template-defined (fixed) |
| Everything else | Linux | User-configurable (CPU/RAM/Disk) |
Templates must have cloud-init and QEMU guest agent enabled.
Perimeter exposes a /metrics endpoint with:
perimeter_http_requests_total— HTTP request count by method/endpoint/statusperimeter_http_request_duration_seconds— Request duration histogramperimeter_vm_provisions_total— VM provisioning by type/statusperimeter_playbook_runs_total— Playbook execution countperimeter_cert_deploys_total— Certificate deploymentsperimeter_vip_operations_total— VIP create/destroy operationsperimeter_template_refreshes_total— Template refresh operations
Add to your Prometheus scrape config:
- job_name: 'perimeter'
static_configs:
- targets: ['<perimeter-ip>:8080']A pre-built dashboard is available at grafana/perimeter-dashboard.json. Import via Grafana UI → Dashboards → Import.
# View logs
journalctl -u perimeter -f
# Restart
sudo systemctl restart perimeter
# Status
sudo systemctl status perimeter
# Edit feature toggles
sudo systemctl edit perimeter
# Add: Environment=PERIMETER_FEATURE_IPAM=0
sudo systemctl restart perimeter# Run locally (development mode)
cd /opt/perimeter
python3 perimeter_app.py
# Run tests
pytest tests/- Code consolidation — Deduplicated ~450 lines across Python and JavaScript (shared utilities for SSH wait, VM types, tfvars I/O, bridges parsing, cascade loaders, flyout toggles, IP validation)
- Hardcoded values removed — Playbooks use Ansible variables, workflows require subnet config, JS reads defaults from backend
- Version endpoint —
GET /api/versionreturns version, node, homelab name, and enabled features - Homelab identity — Name your lab in the installer; appears in the web UI header and VM MOTD banners
- Upgrade script —
installer/upgrade.shfor clean version-to-version upgrades - Worker service — Celery worker service now generated by the installer alongside the main service
- Bug fixes — Duplicate focus trap on cert modal, Proxmox API null safety, PM headers reconstruction
- Celery/Redis job queue replacing subprocess workers
- Fleet deployments (Quick Fleet + Custom Fleet flyout)
- Full
qbranch→perimeterrename - A10 theme removed (single Perimeter theme)
- Installer hardening (Ubuntu 25.10, venv, PEP 668, Age key management)
- CSP-compatible (no inline scripts)
- Initial public release with install script and setup wizard
- Backend: Python 3.9+, Flask
- Frontend: Vanilla JavaScript (ES modules), CSS
- IaC: Terraform (BPG Proxmox provider)
- Config Management: Ansible
- Secrets: SOPS + Age encryption
- Monitoring: Prometheus + Grafana
- Audit: Loki
- Service: systemd
TBD
TBD