Deploying Agents
An agent container runs nginx, dnsmasq, and acme.sh for a site. Deploy one agent per Proxmox node to handle networking for containers on that node.
Agents are deployed manually in Proxmox (not through the manager UI) and should be set up after configuring the site in the manager but before importing the node. This ensures DNS and reverse proxy services are running when the node comes online.
Prerequisites
- Management container deployed and running (Installation Guide)
- A site configured in the manager
- An API key generated from an admin account
- SSH or web UI access to the target Proxmox host
Workflow
1. Pull the Agent Image
On the target Proxmox host:
apt update && apt install -y skopeo
skopeo copy docker://ghcr.io/mieweb/opensource-server/agent:latest \
oci-archive:/var/lib/vz/template/cache/opensource-server-agent.tar
2. Create the Agent Container
In the Proxmox web interface (https://your-proxmox-host:8006):
- Create CT on the target node
- Template: Select
opensource-server-agent - Network: Configure with a static IP in the site's subnet
- Resources: Allocate CPU, memory, and storage as needed
Alternatively, use pct create from the command line:
pct create <vmid> /var/lib/vz/template/cache/opensource-server-agent.tar \
--hostname agent \
--net0 name=eth0,bridge=vmbr0,ip=<static-ip>/24,gw=<gateway> \
--memory 512 \
--features nesting=1 \
--unprivileged 1
3. Configure Environment Variables
Set SITE_ID, MANAGER_URL, and API_KEY via the Proxmox LXC configuration. These propagate to /etc/environment on boot via the base image's environment.sh service.
Add to /etc/pve/lxc/<vmid>.conf:
lxc.environment = SITE_ID=<site-id>
lxc.environment = MANAGER_URL=http://<manager-ip>:3000
lxc.environment = API_KEY=<admin-api-key>
| Variable | Description |
|---|---|
SITE_ID | Numeric site ID from the manager (visible in the URL when viewing the site) |
MANAGER_URL | Base URL of the manager container (e.g., http://192.168.1.10:3000) |
API_KEY | API key from an admin account. Used to authenticate config pulls. |
4. Start and Verify
pct start <vmid>
Verify pull-config is working by checking that nginx and dnsmasq configs were fetched:
# Enter the container
pct enter <vmid>
# Check that configs were pulled
cat /etc/nginx/nginx.conf
cat /etc/dnsmasq.conf
# Test manually
/etc/pull-config.d/nginx
/etc/pull-config.d/dnsmasq-conf
/etc/pull-config.d/dnsmasq-dhcp-hosts
/etc/pull-config.d/dnsmasq-hosts
/etc/pull-config.d/dnsmasq-dhcp-opts
/etc/pull-config.d/dnsmasq-servers
5. Forward Network Traffic
Forward the following ports from the Proxmox host to the agent container:
| Port | Protocol | Service |
|---|---|---|
| 80 | TCP | HTTP (nginx) |
| 443 | TCP | HTTPS (nginx) |
| 443 | UDP | QUIC (nginx) |
| 53 | TCP/UDP | DNS (dnsmasq) |
6. Import the Node
With the agent running, proceed to import the node in the manager. The agent's dnsmasq and nginx will automatically receive updated configurations as containers are created and removed.
How It Works
The agent uses pull-config, a cron-based system that fetches configuration files from the manager every minute.
Each service (nginx, dnsmasq) has its own instance script(s) in /etc/pull-config.d/ that run independently. ETag caching ensures configs are only downloaded when they change.
Dnsmasq is split into 5 pull-config instances: the main config (dnsmasq-conf) triggers a full restart, while the auxiliary files (dnsmasq-dhcp-hosts, dnsmasq-hosts, dnsmasq-dhcp-opts, dnsmasq-servers) trigger a SIGHUP reload. This avoids restarting dnsmasq when only DHCP leases or host records change.