Skip to main content

Node Management

OSAPI can query and update system-level information on managed nodes. All node operations 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, lightweight metrics, and node conditions from the last heartbeat. No jobs are created. Agents also expose typed system facts (architecture, kernel version, FQDN, CPU count, network interfaces, service manager, package manager) gathered every 60 seconds via providers and stored in a separate agent-facts KV bucket with a 5-minute TTL. The API merges registry and facts data into a single AgentInfo response. Agents can be drained for maintenance without stopping the process.
  • 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
HostnameGet or update the system 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
System FactsArchitecture, kernel, FQDN, CPUs, NICs, routes, service/pkg mgr

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 read endpoints require node:read. Hostname update requires node:write. Agent fleet discovery endpoints require agent:read. The built-in admin and write roles include node:read and node:write. The read role includes node:read only.