Requirements & permissions

The install script asks for a root shell, so this page spells out what that root shell does and what privileges the agent is left with afterward. The short version: an unprivileged system user, no open ports, a read-only view of the OS, and disk capabilities only when physical drives exist. The script itself is plain POSIX shell, readable at get.monitorable.net/install.sh — you can read every line before running it.

What the server needs

Requirement	Detail
OS	Linux on x86_64 (amd64) or arm64. Bare metal, VMs, and LXC containers are all supported. The agent is Linux-only.
Init system	systemd — the agent runs as the monitorable-agent.service unit.
Tools	curl, used to fetch the script, binary, and configuration, and openssl, used to check the release signature. The script stops before changing anything if openssl is missing (apt-get install -y openssl / dnf install -y openssl).
Network	Outbound HTTPS (port 443). No inbound ports, no firewall changes.

The agent is a single binary, about 47 MB on disk. On the small server these docs are verified against, it holds 12–16 MB of resident memory and has averaged under 0.1% of one CPU core.

Network traffic is outbound only

Destination	When	What
get.monitorable.net	Install, upgrade and uninstall	The install script.
get.monitorable.io	Install and upgrade	The agent binary, base configuration, service file, and the signed checksum file.
ingest.monitorable.net	Runtime, every 60 seconds	Metrics as gzip-compressed OTLP over HTTPS, authenticated with the server’s API key.

The agent binds no listening ports — ss -ltnp on a monitored server shows nothing owned by it. There is no remote-control channel: the only connection is the one the agent opens to post metrics.

Root installs it, an unprivileged user runs it

Root is needed once, for setup. The install script creates:

• The monitorable system user and group. The user has no login shell (/sbin/nologin) and no password; its home is /var/lib/monitorable, the agent’s only writable directory.
• /opt/monitorable/ — the agent binary, owned by root so the agent can’t replace its own executable. There is no separate launcher.
• /etc/monitorable/collector-config.yaml — the agent configuration, mode 640, readable only by root and the monitorable group.
• /etc/monitorable/agent.env — mode 600, owned by root:root. Holds the server’s API key and the ingest endpoint as environment variables; nothing but root can read it.
• /etc/systemd/system/monitorable-agent.service — the service unit. It references the env file above (EnvironmentFile=) rather than carrying the API key itself, so the unit file — which is world-readable — never exposes the secret.

The service runs as the monitorable user, and the unit sandboxes it further. From the installed unit file:

NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=tmpfs
ReadWritePaths=/var/lib/monitorable
PrivateTmp=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectControlGroups=yes

In practice: the agent can’t gain privileges it wasn’t started with, sees the whole OS read-only except /var/lib/monitorable, gets a private /tmp, and can’t touch kernel tunables, kernel modules, or cgroups. /root and users’ session directories are masked out entirely; /home is re-exposed read-only so the disk-usage panel can measure how full it is, with normal file permissions still applying on top.

Disk (SMART) capabilities are probed, not blanket

Reading SMART health data from drives needs kernel capabilities that most of the agent never uses, so the install script checks /sys/block and grants only what the detected hardware requires:

Detected	Granted to the service
NVMe drive	CAP_SYS_RAWIO + CAP_SYS_ADMIN, membership of the disk group, and a udev rule (/etc/udev/rules.d/99-monitorable-nvme-smart.rules) that lets the disk group open the NVMe controller node read-only.
SATA/SAS drives, no NVMe	CAP_SYS_RAWIO and membership of the disk group.
No physical drive (typical VPS or VM)	Nothing. The unit’s capability set is empty.

NVMe needs the broader grant because SMART reads on NVMe are admin ioctls on Linux. The unit sets CapabilityBoundingSet to the same list as the grant, so the table above is also the ceiling — the agent can’t acquire anything beyond it. Re-running the install command re-probes the hardware, which is how you extend the grant after adding a drive.

SMART data itself appears only for bare-metal servers: virtual disks don’t expose drive health, so on a VM the probe finds nothing and no capability is granted.

Docker socket access

If a docker group exists when the script runs, the monitorable user joins it — the standard way to grant read access to the Docker socket — and the agent reports container metrics. It probes the socket on each collection cycle, so containers show up without any configuration.

If you install Docker after the agent, the group membership is missing. Re-run the install command, or grant it directly:

usermod -aG docker monitorable
systemctl restart monitorable-agent

When the agent lacks a permission

Missing privileges never break monitoring — the affected feature is skipped and reported. The Permission Limitations card at the bottom of the server’s page appears only when the agent skipped a check for lack of a privilege you can grant, and names the check and the grant. Today the two grants above — SMART capabilities and the docker group — are the only ones the agent needs, and both are re-probed by the install command, so the usual fix is to re-run it.

Features a server simply doesn’t have are not permission problems and never appear on the card: a virtual machine has no temperature sensors and no SMART data, so its Temp and SMART tabs stay empty without any entry here.