Skip to main content

Remote agents / multi-node

One AMUD server. Agents on every machine you care about.

Use this when your homelab spans more than one box — for example a Proxmox node, an Unraid NAS, a CasaOS mini-PC, and a plain Docker host. You install amud-server once; you install amud-agent on each machine. The dashboard Nodes strip shows every connected host; container start/stop goes to the agent that owns that node.

flowchart LR
  UI[Dashboard]
  S[amud_server]
  UI --> S
  S --- A1[Agent_PVE]
  S --- A2[Agent_Unraid]
  S --- A3[Agent_CasaOS]
  S --- A4[Agent_Docker]

If you only have one host (server + agent sharing a Unix socket), you can ignore this page.

What each agent can report​

AMUD uses capability profiles (no native Unraid/CasaOS APIs yet):

CapabilityMeaning
hostCPU, RAM, disk, network (always)
dockerContainers + start/stop when Docker socket is available
proxmoxLXC list + controls via local Proxmox API (localhost:8006)

Optional badge on the Nodes strip: AMUD_PLATFORM=proxmox|unraid|casaos|docker.

Your hardwareHow to wire it
Proxmox nodeAgent on that host + PVE_API_TOKEN (talks to local PVE)
UnraidAgent + Docker socket; set AMUD_PLATFORM=unraid
CasaOSAgent + Docker socket; set AMUD_PLATFORM=casaos
Docker-only VPS/PCAgent + Docker socket; set AMUD_PLATFORM=docker

Several Proxmox nodes = one agent per node (each with its own tag and token).

Step-by-step: add a second (or third) node​

1. Prepare the AMUD server​

Keep your existing local agent on UDS if you have one. Additionally open a TCP port for remotes:

AMUD_AGENT_SECRET=your-long-shared-secret
AMUD_AGENT_TCP_LISTEN=0.0.0.0:8050
  • Docker / Compose: publish 8050:8050 and set the env on the dashboard container.
  • Firewall: allow 8050/tcp only from LAN or VPN. Never expose plain TCP to the public internet.

Transport choice (pick one):

ModeWhen to useServer extrasAgent extras
Plain TCPTailscale, WireGuard, trusted LANAMUD_AGENT_TCP_LISTEN onlyAMUD_SERVER_ADDR
TLSHardened LAN / no VPN+ AMUD_AGENT_TLS=1, cert, key+ AMUD_AGENT_TLS=1, CA file

TLS example (server):

AMUD_AGENT_TLS=1
AMUD_AGENT_TLS_CERT=/opt/amud/certs/agent.crt
AMUD_AGENT_TLS_KEY=/opt/amud/certs/agent.key
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout agent.key -out agent.crt -days 825 \
  -subj "/CN=amud.lan"

2. Install agent-only on the remote host​

Do not run a second amud-server.

AMUD_SERVER_ADDR=amud.lan:8050     # or Tailscale IP / MagicDNS name
AMUD_NODE_TAG=unraid-1             # REQUIRED — unique per host
AMUD_AGENT_SECRET=your-long-shared-secret
AMUD_PLATFORM=unraid               # optional
# Docker hosts:
#   mount /var/run/docker.sock
# Proxmox hosts:
#   PVE_API_TOKEN=user@pam!id=...
#   PVE_NODE=pve                   # optional; defaults to hostname

TLS client:

AMUD_AGENT_TLS=1
AMUD_AGENT_TLS_CA=/path/to/agent.crt   # or your CA
# Lab only (discouraged): AMUD_AGENT_TLS_INSECURE=1

3. Wire apps in the dashboard​

  1. Open the dashboard — the Nodes strip lists online tags (CPU/RAM, capabilities).
  2. Click a node to drive the host telemetry cards (CPU / RAM / GPU / disk).
  3. Edit each app → Node tag = the agent tag that runs that container (unraid-1, pve2, …).
  4. Start/stop/restart now targets that agent only.

Settings → Performance also shows a Remote agents snippet you can copy.

4. Verify​

  • Nodes strip shows the new tag as online.
  • App cards for that tag get live container status.
  • Controls on those cards succeed (agent must stay connected).

Environment reference​

Server (amud-server)​

VariablePurposeDefault
AMUD_AGENT_SECRETShared IPC secret (required)—
AMUD_SOCKET_PATHLocal UDS path (Unix)/opt/amud/run/amud.sock
AMUD_AGENT_TCP_LISTENBind for remote agents, e.g. 0.0.0.0:8050off (Unix); Windows uses AMUD_TCP_ADDR
AMUD_AGENT_TLS1 = TLS on the TCP listeneroff
AMUD_AGENT_TLS_CERTPEM certificaterequired if TLS
AMUD_AGENT_TLS_KEYPEM private keyrequired if TLS

Agent (amud-agent)​

VariablePurposeDefault
AMUD_AGENT_SECRETSame secret as serverrequired
AMUD_SOCKET_PATHLocal UDS (when not using TCP)/opt/amud/run/amud.sock
AMUD_SERVER_ADDRhost:port of the AMUD server (remote mode)unset = UDS/local
AMUD_NODE_TAGUnique node id (required with AMUD_SERVER_ADDR)from server config / Local
AMUD_PLATFORMBadge: proxmox / unraid / casaos / dockerempty
AMUD_DOCKER0 disable / 1 force Dockerauto if socket exists
PVE_API_TOKENProxmox API token on that hostunset
PVE_NODEPVE node name/etc/hostname
AMUD_AGENT_TLSUse TLS to the serveroff
AMUD_AGENT_TLS_CATrust store / server cert PEMrequired if TLS (unless insecure)
AMUD_AGENT_TLS_INSECURESkip cert verify (lab only)off

Settings UI (local defaults)​

SettingWhereNotes
Default local agent node tagSettings → PerformanceUsed when the co-located agent has no AMUD_NODE_TAG
App Node tagAdd/Edit appMust match an agent tag for metrics + controls
Proxmox token / enableSettings → InfrastructurePushed to connected agents; remotes should prefer their own PVE_API_TOKEN env
Poll intervalsSettings → PerformanceShared cadence hints pushed in agent config

Docker Compose — remote agent only​

services:
  amud-agent:
    image: tradmss/amud-agent:latest
    environment:
      AMUD_SERVER_ADDR: "amud.lan:8050"
      AMUD_NODE_TAG: "docker-box"
      AMUD_AGENT_SECRET: "your-long-shared-secret"
      AMUD_PLATFORM: "docker"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

On the server compose stack, add AMUD_AGENT_TCP_LISTEN=0.0.0.0:8050 and publish port 8050.

Troubleshooting​

SymptomFix
AMUD_NODE_TAG is requiredSet a unique tag whenever AMUD_SERVER_ADDR is set
node_tag already connectedTwo agents share a tag — rename one and restart
Node never appearsSecret mismatch, firewall, or server missing AMUD_AGENT_TCP_LISTEN
Metrics OK, controls failApp node tag ≠ agent tag, or that agent disconnected
TLS handshake failsAgent AMUD_AGENT_TLS_CA must trust the server cert
Wrong host metricsSelect the correct chip in the Nodes strip