Architecture

How Pillar Works

Pillar is two small components plus a cloud ingestion pipeline. This page explains what each piece does, how they talk to each other, and — just as importantly — what they are built not to do.

1.The Two Components

Component	What it does	Network posture	Filesystem posture	Required?
Pillar Agent	Reads SMART, /proc/diskstats, ZFS/Unraid/TrueNAS pool state, and network interface counters; posts a heartbeat on a poll interval.	Outbound only, TLS 1.3, to Pillar Cloud. Zero inbound listeners.	Read-only root, read-only device/proc/sys mounts, no media dataset mounts.	Always required — this is the only component that talks to Pillar Cloud.
Pillar Observer	Optional eBPF sidecar; measures true per-I/O block latency distributions (p50/p95/p99/p99.9) and request-size histograms that /proc/diskstats cannot provide.	network_mode: none; no external network access. Local Unix socket IPC connects to the Agent.	Read-only root, tmpfs /tmp; talks to the Agent only over a local Unix socket.	Optional. Adds per-I/O distributions and related diagnostics; Agent-only collection still supports mean latency and hardware health.

Full deployment details, capability flags, and mount lists for both components are in Agent & Observer reference.

2.Pairing a Server

Use the installation command generated in Settings → Agent Pairing. The HTTPS installer verifies signed release artifacts:

Settings → Agent Pairing generates a one-time claim token (15-minute expiry) and hands you a one-line install command.
The command downloads a shell installer from your Pillar domain's /join/<token> route over TLS, then runs it with sudo sh.
The installer verifies Docker is reachable, installs a pinned-checksum Cosign binary, and uses it to verify the signed release manifest and the signed Agent image before pulling anything.
It runs a non-destructive --preflight check inside the exact signed image, then launches the hardened container (--read-only --cap-drop=ALL --cap-add=SYS_RAWIO, no Docker socket).
It waits for an authenticated heartbeat, then restarts the container once more without the one-time claim token in its environment — only the paired API key (stored 0600 in a named volume) remains.
On supported failure paths, the installer attempts to restore the previous Agent container. Check its output and verify the restored container and heartbeat; host or Docker failures can prevent recovery.

Generate a fresh claim token for each pairing attempt. Review existing containers and persistent configuration before reinstalling. See Team access for who can generate pairing tokens.

3.What Happens After Pairing

On a poll interval (15 seconds by default, PILLAR_POLL_INTERVAL), the Agent reads local disk, pool, SMART, and network state, optionally merges in the latest aggregated latency window from the Observer over their shared Unix socket, and posts a single heartbeat document to Pillar Cloud. Pillar Cloud never pushes commands unsolicited — supported remediation actions (like a scrub pause or a locator-LED blink) are queued server-side for delivery on an authenticated heartbeat. Completion still depends on host capability, command expiry, and execution results.

An abbreviated, static example of the heartbeat is available on the Security page's Payload Transparency Explorer.

4.What Pillar Does Not Do

Not covered

The documented Agent deployment excludes media dataset mounts. It reads host/device metadata and uses writable configuration and runtime storage. Raw device access is sensitive; validate actual mounts and permissions.

Not covered

Neither component is designed to expose a TCP/UDP listener. The Agent uses outbound TLS 1.3 for Cloud traffic and a local Unix listener for Observer IPC. The Observer uses network isolation (network_mode: none).

Not covered

The documented deployment excludes the Docker socket and drops default capabilities before adding required ones. These controls reduce exposure; they do not establish an absolute guarantee against container escape.

Limitation

Command dispatch is heartbeat-driven, not real-time push — a queued action may be delivered on a subsequent heartbeat. Verify its result and refreshed host telemetry before assuming it took effect.

← Overview Deployment →