Breeze RMM Agent Reference

The Go agent runs on managed devices (Windows, macOS, Linux) and communicates with the Hono API server.

Architecture Overview

agent/
  cmd/breeze-agent/main.go    # Entry point (cobra CLI)
  agent.yaml                   # Config file (auto-generated on enroll)
  internal/
    config/config.go           # Config loading/saving (viper)
    heartbeat/heartbeat.go     # Main run loop, command dispatch, inventory
    websocket/client.go        # Real-time WebSocket connection
    collectors/                # System data collectors (per-platform)
    remote/
      tools/                   # Command handlers (processes, services, files, etc.)
      desktop/                 # WebRTC remote desktop
    terminal/                  # PTY management (per-platform)
    updater/                   # Self-update mechanism
    scripts/                   # Script execution runner
  pkg/api/client.go            # HTTP client for enrollment

CLI Commands

breeze-agent run                        # Start the agent
breeze-agent enroll <key> --server URL  # Enroll with server
breeze-agent version                    # Print version
breeze-agent status                     # Check enrollment status
breeze-agent --config /path/to/file     # Use custom config

Config File (agent.yaml)

agent_id: <sha256-hash>
auth_token: brz_<hex-token>
org_id: <uuid>
site_id: <uuid>
server_url: http://localhost:3001
heartbeat_interval_seconds: 60
metrics_interval_seconds: 30
enabled_collectors:
  - hardware
  - software
  - metrics
  - network

• Location: /etc/breeze/agent.yaml (Linux), /Library/Application Support/Breeze/agent.yaml (macOS), %ProgramData%\Breeze\agent.yaml (Windows)
• Permissions: Directory 0700, file 0600 (contains auth token)
• Auth token: brz_ prefix, stored as SHA-256 hash in DB (agentTokenHash column)

Communication Channels

1. Heartbeat (HTTP Polling)

• POST /api/v1/agents/:id/heartbeat every 60s
• Sends: CPU, RAM, disk metrics + status + agent version
• Receives: pending commands, config updates, upgrade instructions
• Auth: Authorization: Bearer brz_<token>

2. WebSocket (Real-time)

• ws(s)://server/api/v1/agent-ws/:agentId/ws?token=brz_<token>
• Receives commands instantly (no polling delay)
• Sends command results + terminal output
• Auto-reconnect with exponential backoff (1s initial, 60s max, 0.3 jitter)
• Ping/pong keepalive: ping every 54s, pong timeout 60s
• Max message size: 512KB

3. Inventory (HTTP Push)

• Sent on startup + every 15 minutes
• PUT /api/v1/agents/:id/software - software inventory
• PUT /api/v1/agents/:id/disks - disk inventory
• PUT /api/v1/agents/:id/network - network adapters
• PUT /api/v1/agents/:id/connections - active connections
• PUT /api/v1/agents/:id/patches - pending + installed patches
• PUT /api/v1/agents/:id/eventlogs - event logs (every 5 min)

Command Types

All commands use: {id: string, type: string, payload: map[string]any} Results use: {type: "command_result", commandId: string, status: string, result: any}

Process Management

Service Management

File Operations

Terminal (PTY)

Terminal output streams via WebSocket: {type: "terminal_output", sessionId, data} Terminal commands use term- prefix IDs and skip DB persistence.

Windows-Specific

System Commands

Enrollment Flow

1. User runs: breeze-agent enroll <key> --server <url>
2. Agent collects hardware info via collectors.HardwareCollector
3. POST /api/v1/agents/enroll with enrollment key + device info
4. Server returns: {agentId, authToken, orgId, siteId, config}
5. Agent saves config to agent.yaml with 0600 permissions
6. Auth token stored as SHA-256 hash in devices.agentTokenHash

Command Execution Flow

API creates command (DB) → dispatches via WebSocket (or heartbeat response)
  → Agent receives {id, type, payload}
  → heartbeat.executeCommand() dispatches to handler
  → Handler returns tools.CommandResult {status, stdout, stderr, error}
  → Result sent via WebSocket AND HTTP POST to /agents/:id/commands/:cmdId/result

Build & Development

cd agent
make run              # Build and run locally
make build-all        # Cross-compile (windows/linux/darwin, amd64/arm64)
go build -o /tmp/breeze-agent-bin ./cmd/breeze-agent/  # Quick build
/tmp/breeze-agent-bin run  # Run built binary (needs 'run' subcommand!)

Key Dependencies

• github.com/gorilla/websocket - WebSocket client
• github.com/spf13/cobra - CLI framework
• github.com/spf13/viper - Configuration management
• github.com/shirou/gopsutil - System metrics collection
• github.com/pion/webrtc - Remote desktop (WebRTC)

Platform-Specific Files

Many packages have platform-specific implementations:

• *_darwin.go - macOS
• *_linux.go - Linux
• *_windows.go - Windows
• *_other.go - Stub for unsupported platforms

Notable: Terminal PTY uses cgo on macOS (pty_darwin.go) for posix_openpt/grantpt/unlockpt/ptsname.

Dev Push (Fast Binary Update)

Bypasses the full release cycle for rapid agent iteration: build → upload → restart in seconds.

Flow

make dev-push    (reads .env.dev for defaults)
  1. Cross-compile binary (queries device OS/arch from API)
  2. Upload binary via POST /api/v1/dev/push (multipart, JWT or API key auth)
  3. API saves to temp dir, computes SHA256, creates ephemeral download URL (5-min TTL)
  4. API sends `dev_update` command to agent via WebSocket
  5. Agent disables auto_update (persisted to config), downloads binary, verifies checksum
  6. Agent backs up current binary, replaces, restarts

Authentication

Dev-push accepts two auth methods (JWT or API key). Prefer the API key — it doesn't expire hourly.

Option 1: API key (recommended) — Set in .env.dev:

# .env.dev (gitignored, at repo root)
BREEZE_API_KEY=brz_XXXX          # from web UI → Settings → API Keys
BREEZE_DEV_DEVICE=<device-uuid>
BREEZE_API_URL=http://localhost:3001

Then just cd agent && make dev-push — no extra args needed.

The dev-push route sends X-API-Key header when the token starts with brz_, Authorization: Bearer otherwise.

Option 2: JWT — For endpoints that don't accept API keys (e.g. /devices/:id/diagnostic-logs):

# Generate a 1-hour JWT token:
./agent/scripts/gen-jwt.sh                    # uses first user in DB
./agent/scripts/gen-jwt.sh todd@olivetech.co  # specific user

# Use it:
export TOKEN=$(./agent/scripts/gen-jwt.sh)
curl -H "Authorization: Bearer $TOKEN" http://localhost:3001/api/v1/devices/<id>/diagnostic-logs

JWT requirements (if generating manually):

• Library: jose (NOT jsonwebtoken)
• Algorithm: HS256
• Secret: JWT_SECRET from .env (at repo root)
• Required claims: iss: "breeze", aud: "breeze-api"
• Required fields: sub (real user UUID from users table), email, scope: "system", type: "access"
• User lookup: docker exec breeze-postgres-dev psql -U breeze -d breeze -t -c "SELECT id, email FROM users LIMIT 3;"

Usage

# Easiest — uses .env.dev defaults (API key + device ID):
cd agent && make dev-push

# Override device or token:
make dev-push DEVICE=<deviceId>
make dev-push AUTH_TOKEN=<jwt-or-api-key>

# Manual — build + push separately:
cd agent
GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -ldflags "-X main.version=dev-$(date +%s)" \
  -o bin/breeze-agent-dev ./cmd/breeze-agent
curl -X POST http://localhost:3001/api/v1/dev/push \
  -H "X-API-Key: brz_XXXX" \
  -F "agentId=DEVICE_ID" \
  -F "binary=@bin/breeze-agent-dev"

Command Reference

Key Files

Guard Rails

• Production disabled: only works when NODE_ENV !== 'production' or DEV_PUSH_ENABLED=true
• Auto-update disabled: dev_update sets auto_update: false in config to prevent heartbeat from overwriting the dev binary
• Re-enable: set auto_update: true in agent.yaml or re-enroll the device
• Ephemeral: download tokens expire after 5 minutes and files auto-cleanup

Dev Iteration Loop

The intended workflow for debugging/developing agent code: fetch logs → fix code → build & push → check logs.

┌─────────────────────────────────────────────────────────┐
│  1. FETCH LOGS — see what's happening on the agent      │
│                                                         │
│  # Get recent agent logs (shipped from agent → DB)      │
│  GET /api/v1/devices/:id/diagnostic-logs                │
│    ?level=warn,error                                    │
│    ?component=updater                                   │
│    ?search=keyword                                      │
│    ?since=2026-02-15T00:00:00Z                          │
│                                                         │
│  # Or bump log level for more detail (auto-reverts)     │
│  Send `set_log_level` command:                          │
│    {level: "debug", durationMinutes: 30}                │
│                                                         │
│  # Direct DB query for fastest access:                  │
│  psql: SELECT * FROM agent_logs                         │
│    WHERE device_id = '<id>'                             │
│    ORDER BY timestamp DESC LIMIT 50;                    │
├─────────────────────────────────────────────────────────┤
│  2. FIX CODE — edit Go source in agent/internal/...     │
├─────────────────────────────────────────────────────────┤
│  3. BUILD & DEPLOY — push new binary to live agent      │
│                                                         │
│  cd agent && make dev-push                              │
│  # reads .env.dev for API key + device ID               │
│                                                         │
│  Agent restarts with new binary in ~5 seconds.          │
├─────────────────────────────────────────────────────────┤
│  4. CHECK LOGS — verify the fix                         │
│                                                         │
│  GET /api/v1/devices/:id/diagnostic-logs                │
│    ?since=<deploy-time>                                 │
│                                                         │
│  Look for:                                              │
│    - New agent version in logs (dev-<timestamp>)        │
│    - Error/warn messages resolved                       │
│    - Expected behavior in component logs                │
│                                                         │
│  If not fixed → loop back to step 1                     │
└─────────────────────────────────────────────────────────┘

API endpoints used in the loop:

Log shipping pipeline: Agent logging package → buffer → POST /api/v1/agents/:id/logs → agent_logs table → queryable via /devices/:id/diagnostic-logs

Filters: ?level=, ?component=, ?search=, ?since=, ?until=, ?page=, ?limit= (max 1000)

Agent Version Management & Upgrades

Release Pipeline

Tag commit (v*) → GitHub Actions builds all platforms → Assets uploaded to GitHub Releases
  → API syncs versions via POST /api/v1/agent-versions/sync-github
  → Registered in `agent_versions` table with download URLs + SHA256 checksums
  → Agents auto-upgrade via heartbeat response `upgradeTo` field

Version Registry (Database)

The agent_versions table tracks each binary per platform/arch/component.

Auto-Upgrade via Heartbeat

On each heartbeat, the API compares the agent's reported version against the latest registered version:

• Semver builds (e.g. 0.12.0): upgraded when a newer version exists (compareAgentVersions)
• Dev builds (dev-*): always offered the latest release version (dev versions can't be semver-compared)
• The heartbeat response includes upgradeTo: "X.Y.Z" which the agent acts on

Key code: apps/api/src/routes/agents/heartbeat.ts lines ~188-198

Self-Update Mechanism (Agent Side)

1. Agent receives upgradeTo in heartbeat response
2. Calls GET /api/v1/agent-versions/{version}/download?platform=X&arch=Y to get URL + checksum
3. Downloads binary from URL (GitHub CDN, S3, or local API)
4. Verifies SHA256 checksum
5. Backs up current binary to .backup
6. Platform-specific restart:
   • Windows: Spawns detached PowerShell script (stop service → copy binary → start service)
   • Linux: systemctl restart breeze-agent
   • macOS: launchctl kickstart -k system/com.breeze.agent
   • Fallback: syscall.Exec() to replace process
7. On failure, restores from .backup

Key files: agent/internal/updater/updater.go, agent/internal/heartbeat/heartbeat.go

Upgrading from Dev Build to Release

Dev-push sets auto_update: false in the agent config to prevent heartbeat from overwriting dev binaries. To return a device to the release track:

Option 1 — Edit agent config (on the device): Set auto_update: true in agent.yaml, then restart the agent. The next heartbeat will trigger upgrade to latest release.

Option 2 — Re-enroll the device (clean slate).

Note: The compareAgentVersions function returns 0 for dev versions (can't parse dev-* as semver), so the heartbeat has special handling: if agentVersion.startsWith('dev-'), it always sets upgradeTo to the latest release regardless of comparison.

Binary Serving Modes

Controlled by BINARY_SOURCE env var:

Install Scripts

Dynamic installer endpoint: GET /api/v1/agents/install.sh — detects OS/arch, downloads binary, enrolls, installs service.

Security

• Agent auth: brz_ token in Authorization: Bearer header
• Server validates via SHA-256 hash comparison (same pattern as API keys)
• Rate limited: 120 req/60s per agent via Redis sliding window
• WebSocket token passed as query parameter, validated on connect
• Config file restricted to owner-only (0600)
• Mutating commands are audit-logged with actorType: 'agent'