Skip to main content

Node Management

OSAPI can query a variety of system-level information from managed nodes. All node operations are read-only today and run through the job system, so the API server never needs direct access to the host.

Agent vs. Node​

OSAPI separates agent fleet discovery from node system queries:

  • Agent commands (agent list, agent get) read directly from the NATS KV heartbeat registry. They show which agents are online, their labels, and lightweight metrics from the last heartbeat. No jobs are created.
  • Node commands (node hostname, node status) dispatch jobs to agents that execute system commands and return detailed results (disk usage, full memory breakdown, etc.).

What It Manages​

ResourceDescription
HostnameSystem hostname
StatusUptime, OS name and version, kernel, platform info
DiskPer-mount usage (total, used, free, percent)
MemoryRAM and swap usage (total, used, free, percent)
Load1-, 5-, and 15-minute load averages

How It Works​

Node queries are submitted as jobs. The CLI posts a job to the API server, the API server publishes it to NATS, an agent picks it up and reads the requested system information, then writes the result back to NATS KV. The CLI polls for the result and displays it.

Network and command operations are also nested under the node — see Network Management and Command Execution for those domains.

You can target a specific host, broadcast to all hosts, or route by label. See Node CLI Reference for job-based commands and Agent CLI Reference for registry-based fleet discovery, or the API Reference for the REST endpoints.

Configuration​

Node management uses the general job infrastructure. No domain-specific configuration is required. See Configuration for NATS, agent, and authentication settings.

Permissions​

Node job endpoints require the node:read permission. Agent fleet discovery endpoints require the agent:read permission. The built-in admin, write, and read roles all include both permissions.