Agent Info

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