Skip to main content

Agent Overview

The Proxima Agent is a lightweight Go binary deployed on every managed server. It continuously collects system inventory and sends heartbeats to the Proxima Console backend, providing real-time visibility into your infrastructure.

Architecture​

What It Collects​

The agent gathers the following information from each managed host:

  • Host info -- hostname, OS, kernel version, architecture, IP addresses, uptime, boot time, timezone, virtualization type/role, cloud provider/region/zone
  • Labels -- operator-defined key-value metadata, both static (from config) and dynamic (computed by running shell commands on a schedule)
  • Services -- all systemd service units with real statuses (running, exited, stopped, failed, starting, stopping)
  • Packages -- installed packages via dpkg (Debian/Ubuntu) or rpm (RHEL/CentOS)
  • Open ports -- listening TCP/UDP sockets discovered via ss
  • Network interfaces -- interface names, addresses, and link state
  • Users -- local user accounts from /etc/passwd
  • Processes -- full process list snapshot (PID, name, command, username, state, CPU%, memory%, RSS, threads) collected every 30 seconds (configurable via PROXIMA_AGENT_PROCESS_INTERVAL)

Communication​

The agent communicates exclusively via NATS using outbound connections only. No inbound ports need to be opened on the client side, which simplifies firewall rules and reduces the attack surface. All data flows from the agent to the NATS server, where the backend consumes it.

Self-Monitoring​

The agent monitors its own resource usage and exports 26 metrics alongside system metrics. These include CPU usage, memory (RSS/VMS), file descriptors, context switches, disk I/O, Go runtime statistics (heap, stack, GC), and NATS transport metrics (throughput, RTT, outbox depth). All self-monitoring metrics carry an agent_version label for cross-version comparison. See Metrics Collected for the full list.

Resource Footprint​

The agent is designed for minimal resource consumption:

  • GOMAXPROCS(1) -- restricts the Go runtime to a single OS thread, keeping CPU usage low on production servers
  • Small memory footprint suitable for running alongside production workloads
  • Buffered internal channels prevent backpressure from affecting the host
  • On-disk outbound buffer -- enabled by default, the agent spills outbound telemetry to {data_dir}/buffer while NATS is unreachable and replays it oldest-first on reconnect, mitigating the drop-on-full behavior of the in-memory channel. Tunable via PROXIMA_AGENT_BUFFER_ENABLED, PROXIMA_AGENT_BUFFER_MAX_BYTES, and PROXIMA_AGENT_BUFFER_MAX_AGE
  • Configurable memory limit -- set PROXIMA_AGENT_MEMORY_LIMIT_MB to enforce a Go soft memory limit via debug.SetMemoryLimit
  • Per-collector timeout -- PROXIMA_AGENT_COLLECTOR_TIMEOUT (default 30s) ensures timed-out collectors degrade gracefully without blocking the agent

Graceful Shutdown​

The agent listens for SIGINT and SIGTERM signals and performs a clean shutdown. This includes draining in-flight NATS messages and closing connections, ensuring no data is lost during service restarts or host maintenance.

Configuration​

The agent is configured through a combination of a YAML configuration file and environment variable overrides. Environment variables take precedence over YAML values, which in turn take precedence over hardcoded defaults. See the Configuration page for full details.