Installing the Linux agent

Observare documentation

The Observare agent is a small Go binary that runs on one of your Linux servers and reports back to Observare over outbound HTTPS. You install it on a host that sits inside a network Observare's cloud workers can't reach — a private VLAN, a host behind a firewall, a box inside a Docker network — and it becomes your eyes in there. Once installed and authenticated, the agent can run four kinds of monitor for you: process checks, docker container checks, and internal uptime or port checks.

The agent is Linux-only, requires no inbound firewall rules, and runs as a hardened systemd service under your regular user account — not root.

What the agent does

Every 60 seconds, the agent POSTs a system-stats snapshot to Observare — CPU, RAM, disk, uptime, load average, OS info, and the running version. That's what makes an agent show up as Online in the web UI with live numbers.

Every 30 seconds, it pulls its assigned monitor list down from the server, diffs it against what's currently running, and starts or stops per-monitor goroutines to match. The practical effect: when you add, pause, or remove a monitor in the web UI, the agent picks up the change within 30 seconds.

Each assigned monitor runs on its own independent schedule with its own ticker — 5, 10, or 15 minutes depending on how you configured it. Every check result goes back to Observare for storage, incident tracking, and alerting.

Install

The recommended install is a one-liner that detects your architecture, downloads the latest agent binary, verifies it's a valid ELF executable, and drops it at /usr/local/bin/observare:

curl -fsSL https://observare.io/install.sh | sudo sh

The script supports both x86_64 and aarch64 / arm64 hosts. It bails out with a friendly error if you forget sudo, because it has to write to /usr/local/bin.

If you'd rather read the script before running it:

curl -fsSL https://observare.io/install.sh -o install.sh
less install.sh
sudo sh install.sh

After the binary is installed, the agent is on your PATH but not yet authenticated and not yet running as a daemon. The next three steps take care of that.

Authenticate the agent

observare auth

This uses the same device-authorization flow as the GitHub CLI and Stripe CLI. The command prints an authorize URL and polls in the background. You open the URL in your browser, log into Observare as the account owner, and click Approve. The agent picks up the approval within a couple of seconds and writes its API key and agent ID to ~/.observare/config.json.

$ observare auth
Requesting authorization token from https://observare.io…

Open the following URL in your browser, log into Observare,
and click Approve to authorise this agent:

   https://observare.io/authorize-agent?token=6nS-o6soWdmq2PgyXbV0cwD4kNcCJJOU

Waiting for approval (expires in 15m 0s)…

✓ Agent approved and authenticated.
  Agent ID:   ag_4GSXmHvvUbCDEzjktKXoAr0Q
  Config:     /home/alice/.observare/config.json

The authorize URL is valid for 15 minutes. If you miss that window, re-run observare auth to get a fresh one.

The Observare agent authorisation page in the browser showing the requesting agent's details, the alert-channel checklist, and the Approve button

On the authorize page you'll also see a checklist of your existing alert channels. Tick the ones you want to receive agent-offline and agent-recovery notifications on — you can change this later from the Agents page in the web UI, but the default behaviour is useful to set up-front.

Account limit: Each Observare account can have up to 5 agents authenticated at once. If you need more, contact support.

Add monitors

observare config

This opens an interactive menu on the command line. From here you can add any of the four agent-side monitor types, list what's already configured, or remove an existing monitor without leaving the terminal.

Observare agent configuration
  Server:   https://observare.io
  Agent ID: ag_4GSXmHvvUbCDEzjktKXoAr0Q

What would you like to do?
  1) Add uptime monitor
  2) Add port monitor
  3) Add process monitor
  4) Add Docker container monitor
  5) List this agent's monitors (0 currently)
  6) Remove a monitor
  q) Quit
>

Each Add option prompts you for a friendly name, the thing to check, the interval (5, 10, or 15 minutes), and which of your existing alert channels to attach. The channel list comes from the server on every config pull — any channel you've set up in the web UI is available to attach here.

See the dedicated docs for each type:

Non-interactive commands

If you'd rather skip the menu — for scripts, or when you already know the ID of the monitor you want to remove — these one-shots work too:

observare list          # Print every monitor this agent owns
observare status        # Summary: agent ID, version, systemd state, monitor counts
observare remove <id>   # Delete a monitor by ID (prompts for y/N)

Every monitor you add from the CLI is immediately visible on the matching monitor page in the web UI, and can be edited (renamed, interval changed, alert channels adjusted) or paused from the web UI without touching the CLI.

The Agents list page in the web UI showing the newly-authorised agent with an Online status dot, its monitor count, and alert channel count

Install as a systemd service

sudo observare install

This writes a hardened systemd unit to /etc/systemd/system/observare-agent.service, enables it, and starts it. The daemon runs under your regular user account — not root — and survives reboots.

The generated unit uses Restart=always with a 5-second back-off, so if the agent ever crashes the service recovers within a few seconds and the server-side offline detection (which waits 120 seconds before alerting) won't even notice. Logging goes to the systemd journal:

# Current status + last 10 log lines
systemctl status observare-agent

# Live-tail the log
journalctl -u observare-agent -f

# Errors only
journalctl -u observare-agent -p err
Why sudo? The install command needs root to write to /etc/systemd/system/ and to copy the binary to /usr/local/bin if it isn't already there. It reads SUDO_USER to figure out which user's config to preserve, so run it via sudo from your normal account — not by switching to root first.

Once the systemd service is running, you can close the terminal and walk away — the agent keeps reporting and checking until you stop it.

The Agent detail page in the web UI showing live CPU, RAM, and disk gauges, system details, and the agent's monitors table

Upgrading the agent

Future agent releases are published through the same installer URL. When the web UI shows a stale-version warning next to the agent, or when you see this in the journal:

[version] update available: running 0.0.4, latest is 0.0.5 — upgrade with: curl -fsSL https://observare.io/install.sh | sudo sh

stop the service, re-run the installer, and start it again:

sudo systemctl stop observare-agent
curl -fsSL https://observare.io/install.sh | sudo sh
sudo systemctl start observare-agent

Your ~/.observare/config.json is never touched by the installer or the agent itself, so you keep your authentication across upgrades. Your assigned monitors are stored server-side — they also survive.

Uninstalling

Just the systemd service

sudo observare uninstall

This stops the daemon, disables auto-start at boot, removes the unit file, and runs daemon-reload. The binary at /usr/local/bin/observare and your config at ~/.observare/ are left in place so a future sudo observare install can reuse them without a fresh observare auth cycle.

Full wipe

  1. In the web UI, open Agents, click into this agent, and click Delete. The server cascades the delete to every monitor the agent owned plus all their check history — this cannot be undone.
  2. Uninstall the systemd service: sudo observare uninstall
  3. Remove the binary: sudo rm /usr/local/bin/observare
  4. Remove the config: rm -rf ~/.observare

After those four steps there's no trace of the agent on your host and no record of it on the server.

Troubleshooting

The Agents list page showing one online agent and one with a red Offline status dot, illustrating the failure state the troubleshooting steps address

The agent shows Offline in the web UI

Observare marks an agent offline when its last system report is older than 120 seconds (2× the 60-second reporting interval). The usual causes:

  • Outbound HTTPS blocked. The agent needs outbound access to observare.io:443. No inbound rules required.
  • Daemon isn't running. Run systemctl is-active observare-agent and systemctl status observare-agent to confirm. If the service is failed, journalctl -u observare-agent --since "5 minutes ago" will show the reason.
  • Clock skew. A system clock that's hours off will mess with certificate validation on the outbound HTTPS request. timedatectl will tell you if the clock is sane.

"authentication failed — your API key is no longer valid"

The agent's API key was revoked — almost always because you deleted the agent record from the web UI. Delete ~/.observare/config.json and re-run observare auth to re-authorise with a fresh key.

A monitor's checks are failing but the target works when you hit it manually

Reproduce the check from the agent's host, as the user the daemon runs under:

# Uptime check
sudo -u alice curl -I http://10.0.0.5:8080/health

# Port check (TCP)
sudo -u alice timeout 5 bash -c '</dev/tcp/10.0.0.5/5672 && echo open'

If the manual check fails too, it's a real environmental issue — firewall, DNS, routing. If it succeeds, double-check the monitor's timeout and expected status code in the web UI.

Can't reach observare.io from the agent host

curl -v https://observare.io/api/agent/auth/token

A 400 Invalid input response means you reached the server (the endpoint expects a POST body it didn't get). Any other result points at DNS, routing, or outbound HTTPS filtering.

What's next