Skip to main content

​
Multi-Endpoint Setup

In a distributed deployment, multiple Guard agents on different machines report to a centralized Manager server. The Manager provides fleet-wide visibility, cross-agent threat correlation, and centralized policy distribution.

​
Architecture

[Machine A: Manager]                [Machine B: Guard Agent]
+-------------------+               +---------------------+
| Manager Server    |<-- heartbeat --| GuardEngine         |
| :8443             |<-- events   --| (learning/protection)|
|                   |-- policy   -->|                     |
+-------------------+               +---------------------+
        ^
        |                            [Machine C: Guard Agent]
        |                            +---------------------+
        +<-- heartbeat/events -------| GuardEngine         |
        +--- policy ---------------->|                     |
                                     +---------------------+

​
Deploy the Manager

1

Generate an Authentication Token

Create a secure token for Manager-Agent communication:
export MANAGER_TOKEN=$(openssl rand -hex 32)
echo $MANAGER_TOKEN
Store this token securely. Every Guard agent needs it to register with the Manager.
2

Start the Manager Server

panguard manager --port 8443 --auth-token "$MANAGER_TOKEN"
The Manager accepts connections from Guard agents and provides:
  • Agent Registry — Tracks up to 500 registered agents
  • Threat Aggregator — Correlates threats across agents by source IP, malware hash, and attack pattern
  • Policy Engine — Distributes centralized rules and configuration
  • SSE Stream — Real-time event stream for the admin dashboard
3

Verify the Manager is Running

curl -H "Authorization: Bearer $MANAGER_TOKEN" \
  http://localhost:8443/api/overview

​
Deploy Guard Agents

On each endpoint machine:
1

Install Panguard

npm install -g @panguard-ai/panguard
2

Authenticate

panguard login
3

Start Guard with Manager Connection

panguard guard start \
  --manager-url "http://manager-host:8443" \
  --manager-token "your-secure-token" \
  --data-dir /var/panguard-guard
The agent will:
  1. Register with the Manager on startup
  2. Send heartbeats every 30 seconds
  3. Report detected threats in real-time
  4. Poll for policy updates every 5 minutes

​
Agent Lifecycle

PhaseEndpointIntervalDescription
RegistrationPOST /api/agents/registerOnce (startup)Agent sends hostname, OS, version; receives unique agentId
HeartbeatPOST /api/agents/:id/heartbeatEvery 30sCPU/memory usage, events processed, mode, uptime
Threat ReportPOST /api/agents/:id/eventsReal-timeDetected threats sent immediately
Policy PollGET /api/policy/agent/:idEvery 5 minAgent checks for updated policies
Stale Detection—Every 30s (server)Agents without heartbeat for 90s are flagged stale
DeregistrationDELETE /api/agents/:idManualRemoves agent from fleet

​
Cross-Agent Threat Correlation

The Manager’s Threat Aggregator correlates threats across all agents in real-time:
  • Source IP correlation — Same attacker IP seen on multiple endpoints triggers escalation
  • Malware hash correlation — Same malware fingerprint across agents indicates an active campaign
  • Attack pattern correlation — Related MITRE ATT&CK patterns within a 5-minute window
Cross-agent correlation uses a 5-minute sliding window with 24-hour data retention. Threats correlated across 3+ agents are automatically elevated to CRITICAL severity.

​
Policy Distribution

The Policy Engine allows centralized control over all Guard agents: 
# Set a global policy
curl -X POST -H "Authorization: Bearer $MANAGER_TOKEN" \
  -H "Content-Type: application/json" \
  http://manager-host:8443/api/policy \
  -d '{
    "autoRespondThreshold": 85,
    "ipBlocklist": ["203.0.113.0/24"],
    "alertChannels": ["slack"]
  }'
Policy changes propagate to all agents within their next 5-minute poll cycle.

​
Real-Time Monitoring

​
SSE Event Stream

Stream events from all agents in real-time: 
curl -N -H "Authorization: Bearer $MANAGER_TOKEN" \
  http://manager-host:8443/api/events/stream

​
Fleet Overview

curl -H "Authorization: Bearer $MANAGER_TOKEN" \
  http://manager-host:8443/api/overview

​
Manager Configuration

​
Environment Variables

VariableDefaultDescription
MANAGER_PORT8443HTTP server port
MANAGER_AUTH_TOKEN(none)Bearer token for API authentication
MANAGER_MAX_AGENTS500Maximum registered agents
MANAGER_HEARTBEAT_TIMEOUT_MS90000Heartbeat timeout before marking agent stale
MANAGER_HEARTBEAT_INTERVAL_MS30000Interval for stale agent checks
MANAGER_CORRELATION_WINDOW_MS300000Cross-agent threat correlation window (5 min)
MANAGER_THREAT_RETENTION_MS86400000Threat data retention (24 hours)
CORS_ALLOWED_ORIGINS(none)Comma-separated allowed CORS origins

​
Optional SQLite Persistence

For large deployments, enable SQLite for persistent storage: 
panguard manager --port 8443 --auth-token "$MANAGER_TOKEN" --db /var/panguard-manager/data.db

​
Production Deployment

For production, install the Manager as a systemd service and place it behind a TLS-terminating reverse proxy. See the System Service guide and Docker Deployment guide.

​
Security Checklist

  • Generate a strong authentication token (openssl rand -hex 32)
  • Use TLS termination (nginx/Caddy reverse proxy)
  • Restrict Manager port (8443) to Guard agent networks only
  • Run as a non-root system user
  • Set NODE_ENV=production for hardened mode
  • Store secrets in environment files with chmod 600

Architecture

Full technical architecture of the Manager-Agent system.

System Service

Install Manager and Guard as systemd/launchd services.

Docker Deployment

Run the full stack with Docker Compose.

Threat Cloud

Centralized threat intelligence across your fleet.