--- title: watchfor-agent: Open-Source Linux Monitoring Agent description: watchfor-agent is WatchFor's open-source Linux host agent: one static Go binary, a one-line install, outbound HTTPS only, signed and reproducible releases. canonical: https://watchfor.io/agent --- # The Open-Source Linux Monitoring Agent You Can Read Before You Run A host agent runs on every server you give it, so you should be able to audit it first. watchfor-agent is Apache-2.0 on GitHub and opens no port. Install on a systemd Linux host (amd64 or arm64) Copy curl --proto '=https' --tlsv1.2 -fsSL https://watchfor.io/agent/install.sh | sudo sh -s -- --token Needs root, systemd, curl, tar, sha256sum and useradd — all checked before anything is touched. The host token comes from Hosts → New host in WatchFor; pass --token - to type it on the terminal instead of leaving it in your shell history. [Get a host token](/auth/sign-up)[Plans and host limits](/pricing) [Source on GitHub](https://github.com/watchfor-io/agent)[Releases](https://github.com/watchfor-io/agent/releases)[Documentation](/docs/hosts)[Server monitoring](/server-monitoring) ## What a Host Agent Owes the Person Who Installs It Every claim below is in the README, the systemd unit or the CI workflow, so you can check it ### One-Line Install One curl line downloads the release for your architecture, verifies it, creates the unprivileged watchfor-agent user, writes the token to a 0600 file and an agent.yml with every key explained, and enables the systemd unit. No minisign package, no package repository. Prefer not to pipe a script into a shell? Install by hand in four commands. ### Outbound HTTPS Only Nothing listens on the host. The agent posts one gzip-compressed JSON batch per interval to ingest.watchfor.io over TLS 1.2 or newer and refuses redirects. Release files are fetched only during an upgrade, and the cloud's link-local metadata service is asked only when the firmware says you are on that cloud — never if facts.cloud_metadata is false. ### Runs Unprivileged The service runs as its own system user with ProtectSystem=strict, an empty capability set, NoNewPrivileges, PrivateTmp, a system-call filter, MemoryDenyWriteExecute and a memory cap. Everything the four modules read is readable without root on a standard kernel; the rare exception is granted as one capability in a drop-in, never by running as root. ### Signed and Reproducible Releases Every release ships checksums.txt with a minisign signature made in CI; the public key is printed in the README and compiled into the agent. Binaries are static, built from the tag with CGO_ENABLED=0 and -trimpath, and a second CI job rebuilds the tag on a fresh runner and fails if a byte differs. Each asset carries a GitHub build-provenance attestation, CI actions are pinned by digest, and staticcheck, govulncheck and gosec run on every build. ### The Screen Run watchfor-agent with no command and one screen shows the machine: live CPU, memory, load, disks, network and busiest processes, the exact batch the next push carries, every setting editable in place, the service with its journal, updates and maintenance. Arrow keys move, Enter opens, Esc goes back. It needs no token to look around. ### Health Check and Safe Repairs Is agent.yml there and does it parse, is the token file private, is the binary writable by others, does the service user exist, is the service running and enabled, can the host reach WatchFor over TLS. Each answer that can be repaired safely says how, and one row applies them all. For scripts: watchfor-agent health exits 1 on a failure, and health -fix repairs first. ### Spools When WatchFor Is Unreachable Batches wait in /var/lib/watchfor-agent, up to spool.max_mb with the oldest dropped first, and replay in order after the next successful push. A restart costs nothing either: the spool holds the one or two seconds it takes. A cron-driven host uses the same directory and catches up on its next run. ### Updates You Control Nothing changes on disk unless you ask. sudo watchfor-agent upgrade installs the release the server reported; the opt-in daily timer does the same, and auto-update off removes it. Signature, checksum and an exact-version run must all pass, the swap is an atomic rename, a lock keeps two upgrades from racing, and the running daemon never replaces itself — a separate root-run one-shot does. ## From one command to a host page Create a host, copy the install line and run it on the server. Run watchfor-agent with no command to see live readings every two seconds. The Batch pane lists every value the next push will carry, by name. Pick processes to watch from the ones running now, such as nginx. Health check confirms the install: files, permissions, service, connection. Update checks for a newer release and verifies its signature first. On db-1 the agent lists each postgres process and its memory use. Each server shows its agent version, architecture and operating system. ## What You Are Trusting, Spelled Out watchfor-agent is Apache-2.0 on GitHub, written in Go with a handful of dependencies (YAML, x/crypto and the Charm terminal libraries for the screen), and it reads /proc and /sys — nothing is executed from configuration and no command is ever accepted from the server. The server's whole answer to a batch is how many samples it kept, the shortest interval your plan allows and the newest release version. Hosts are included from the Starter plan up: 1 host on Starter, 5 on Pro, 25 on Business and unlimited on Enterprise, pushing every 60 seconds on Starter and Pro and every 15 seconds on Business and Enterprise. [Start monitoring now](/auth/sign-up) Apache-2.0 source on GitHub: read it, build it, diff your build against the release One static binary for amd64 and arm64 — no runtime, no package repository, no extra packages Outbound HTTPS only: no inbound port, no firewall rule, no credentials that leave the host Runs as its own user under a hardened systemd unit, or from cron with no daemon at all watchfor-agent check prints the exact batch it would send — without a token, without sending Signed checksums, a reproducibility job and provenance attestations on every release One YAML file; unknown keys are an error, so a typo fails at start instead of monitoring nothing The token lives in a 0600 file or an environment variable, and the screen never shows it back ## From Token to First Alert One token per host; the agent does the rest 1 ### Get a Host Token In WatchFor, open Hosts, add a host and name it (the server's hostname is a fine default). Copy the install command with the token. It is shown once and is one per host; Rotate token on the host page issues a new one and invalidates the old within a minute. 2 ### Run the One Line Paste the command on the server. It checks its prerequisites, downloads and verifies the release, creates the user, writes the token and agent.yml, enables the service and asks whether to turn on daily auto-update. Want to look first? Download the tarball and run watchfor-agent check before anything is enabled. 3 ### It Appears in Hosts Within a Minute The first batch carries memory, disk and process readings plus the host facts; rates such as CPU and network throughput need a second sample and arrive with the next push. The host shows Online and the charts fill in. The server answers each batch with the shortest interval your plan allows, so there is no interval to tune. 4 ### Alerts Are Already On Every host starts with Agent Silent, Disk Almost Full and Memory Pressure rules, routed to your default contact group. Add CPU, load, I/O wait, swap, inodes, reboot and watched-process rules from the Alerting tab, each with its own warning and critical levels. ## Where watchfor-agent Fits The same binary, four ways to run it ### Verify Before You Trust Security teams and auditors get a checklist instead of a promise: Apache-2.0 source, the minisign public key printed in the README, checksums.txt.minisig on every release, a CI job that rebuilds the tag and compares byte for byte, and gh attestation verify for provenance. watchfor-agent verify checks a downloaded release; health -deep compares the binary already on disk with the release WatchFor signed. ### Fleets Under Configuration Management One agent.yml per host: a name, tags such as env: prod and role: web, the mounts, disks and interfaces that matter, the processes to watch by name. The installer runs unattended with the token in WATCHFOR_TOKEN and --plain output for logs, and a changed agent.yml that validates is picked up within half a minute — no restart task needed. ### Edge and ARM Machines The same static binary ships for arm64, so a Graviton instance, an ARM server in a rack or a small box at the edge reports the same way as anything else. ARM CPUs, which report no model name, are named from their implementer and part numbers, so the host page says Neoverse-N1 rather than unknown. Batches spool on disk through a flaky uplink and replay in order when it returns. ### Cron Where No Daemon Is Wanted watchfor-agent once collects, pushes one batch and exits: a single line in /etc/cron.d, no long-running process, no systemd unit. It takes two samples a second apart so rates are real, uses the same spool as the daemon, and catches up on the next run after a missed push. Cron's floor is a minute; your plan's interval applies on top. ## Frequently asked questions What people ask before they run it on a server [All questions→](/faq)[Ask us directly](/contact) Is watchfor-agent open source, and under which license? Yes. The source is at github.com/watchfor-io/agent under the Apache-2.0 license. It is written in Go; outside the standard library the agent itself uses gopkg.in/yaml.v3 and golang.org/x/crypto, and the screen adds the Charm terminal libraries. make build produces the same static binary that ships in a release (CGO_ENABLED=0, -trimpath, version from git describe), so you can build the tag and compare the bytes yourself. Changes go through the process in CONTRIBUTING.md. What does the agent send, and where does it go? Can WatchFor run commands on my server? Does it need root? How big is it, and how much CPU and memory does it use? How do updates work, and can I turn them off? How do I verify a release? Can I install it with Ansible or another configuration management tool? How do I remove it? Which distributions and architectures are supported? ## From our blog Guides, deep-dives, and best practices from the WatchFor team [Guides ### "Permissions 0644 are too open"? Fix it with the Chmod Calculator Oct 04, 2026·6 min readRead article](/blog/how-to-calculate-chmod-permissions)[DevOps ### The best server monitoring tools in 2026, sorted by how many servers you have Oct 03, 2026·9 min readRead article](/blog/best-server-monitoring-tools)[Monitoring ### Server Monitoring Basics: CPU, memory, disk and network Feb 18, 2026·3 min readRead article](/blog/server-monitoring-basics) ## Read It, Then Run It Clone the repository, build it, run watchfor-agent check and compare the output with what this page claims. When you are satisfied, add a host in WatchFor, paste one line on the server, and it reports within a minute. Hosts are included from the Starter plan. [Get a host token](/auth/sign-up)[View documentation](/docs/hosts) --- Canonical page: https://watchfor.io/agent · Site guide: https://watchfor.io/llms.txt