Observer Docs

The agent is published as a single-file binary per platform. Each binary embeds the Bun runtime + every dependency, so the install collapses to “download, chmod, run”. Use this path on minimal hosts that cannot or should not run Docker.

Prerequisites

An agent key from the Observer console (Agents > Add agent).
A reachable Prometheus URL, if you plan to use Prometheus probes. PROMETHEUS_SERVER_URL is optional: without it the agent starts, logs a warning, and Prometheus probes report no_data. Active probes (HTTP, TCP, DNS, and the rest) work either way.

Proxies, private CAs and restricted egressIf the host reaches the internet through a proxy, a TLS-intercepting proxy or a private CA, or cannot pull from public registries, see Run behind a proxy or in a restricted network.

Steps

Download and verify

Releases live at github.com/useobserver/agent/releases. Each release publishes five binaries plus a SHA256SUMS.txt checksum file (named SHA256SUMS in releases before 1.6.0).

Platform	File
Linux x64	`observer-agent-linux-x64`
Linux arm64	`observer-agent-linux-arm64`
macOS x64	`observer-agent-darwin-x64`
macOS arm64	`observer-agent-darwin-arm64`
Windows x64	`observer-agent-windows-x64.exe`

On Linux and macOS, this picks the right file from uname, downloads it, and checks it against the published checksums:

VERSION=1.8.2
case "$(uname -s)-$(uname -m)" in
  Linux-x86_64|Linux-amd64) ASSET=observer-agent-linux-x64 ;;
  Linux-aarch64|Linux-arm64) ASSET=observer-agent-linux-arm64 ;;
  Darwin-arm64) ASSET=observer-agent-darwin-arm64 ;;
  Darwin-x86_64) ASSET=observer-agent-darwin-x64 ;;
  *) ASSET=unsupported; echo "No Observer Agent binary for $(uname -s) $(uname -m)" >&2 ;;
esac
BASE=https://github.com/useobserver/agent/releases/download/agent-v${VERSION}
curl -fsSLO "$BASE/$ASSET"
curl -fsSLO "$BASE/SHA256SUMS.txt"
# sha256sum on Linux, shasum on macOS; fails on a mismatch
if command -v sha256sum >/dev/null; then SHA256="sha256sum"; else SHA256="shasum -a 256"; fi
grep " $ASSET$" SHA256SUMS.txt | $SHA256 -c -
sudo mkdir -p /usr/local/bin
sudo install -m 0755 "$ASSET" /usr/local/bin/observer-agent

To always take the newest release instead, set BASE to https://github.com/useobserver/agent/releases/latest/download. The install command in the console (Agents > Add agent, install target Binary, systemd or launchd) runs the same detection with your agent key already filled in.

macOS: clear the quarantine flag

macOS Gatekeeper refuses to run a binary that carries the quarantine flag (set on files from a browser download or AirDrop) and reports that it cannot be opened. Clear it once:

sudo xattr -d com.apple.quarantine /usr/local/bin/observer-agent 2>/dev/null || true

The command does nothing when the flag is not set. Files downloaded with curl usually do not carry it.

Run

AGENT_KEY=obs_live_... \
CLOUD_SERVER_URL=https://use.observer \
PROMETHEUS_SERVER_URL=http://prometheus.local:9090 \
observer-agent

The agent runs in the foreground: logs print to the terminal and Ctrl-C stops it. The dashboard listens on http://localhost:10101. The console’s Agents page marks the agent as running within 90 seconds. To keep it running in the background, use systemd on Linux or launchd on macOS (below).

Linux: run as a systemd service (optional)

/etc/systemd/system/observer-agent.service

[Unit]
Description=Observer agent
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/observer-agent.env
StateDirectory=observer-agent
WorkingDirectory=/var/lib/observer-agent
ExecStart=/usr/local/bin/observer-agent
Restart=on-failure
RestartSec=5s
User=observer

[Install]
WantedBy=multi-user.target

sudo install -m 600 -o root -g root /dev/stdin /etc/observer-agent.env <<'EOF'
AGENT_KEY=obs_live_...
CLOUD_SERVER_URL=https://use.observer
PROMETHEUS_SERVER_URL=http://prometheus.local:9090
EOF
sudo useradd --system --no-create-home observer 2>/dev/null || true
sudo systemctl daemon-reload
sudo systemctl enable --now observer-agent

Logs: journalctl -u observer-agent -f.

macOS: run as a launchd service (optional)

A per-user LaunchAgent starts the agent now and at every login, and restarts it if it exits. launchd passes no shell environment to the process, so every variable the agent needs, including secrets that probes reference by name (connection_string_ref, header_refs and the like), goes in the plist’s EnvironmentVariables. The plist holds the agent key, so only you may read it.

mkdir -p ~/Library/LaunchAgents ~/Library/Logs "$HOME/Library/Application Support/observer-agent"
cat > ~/Library/LaunchAgents/use.observer.agent.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>use.observer.agent</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/observer-agent</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>AGENT_KEY</key>
    <string>obs_live_...</string>
    <key>CLOUD_SERVER_URL</key>
    <string>https://use.observer</string>
    <key>PROMETHEUS_SERVER_URL</key>
    <string>http://prometheus.local:9090</string>
  </dict>
  <key>WorkingDirectory</key>
  <string>$HOME/Library/Application Support/observer-agent</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>ThrottleInterval</key>
  <integer>5</integer>
  <key>StandardOutPath</key>
  <string>$HOME/Library/Logs/observer-agent.log</string>
  <key>StandardErrorPath</key>
  <string>$HOME/Library/Logs/observer-agent.log</string>
</dict>
</plist>
EOF
chmod 600 ~/Library/LaunchAgents/use.observer.agent.plist

# Load it (bootout replaces an earlier copy)
launchctl bootout gui/$(id -u)/use.observer.agent 2>/dev/null || true
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/use.observer.agent.plist

The heredoc is unquoted so that $HOME expands to the absolute paths launchd needs. Escape any $ in a value you add (\$).The agent keeps its local queue in ~/Library/Application Support/observer-agent, its working directory. Logs go to ~/Library/Logs/observer-agent.log:

tail -f ~/Library/Logs/observer-agent.log

After you edit the plist, run the two load commands again. To stop the agent and remove it from login:

launchctl bootout gui/$(id -u)/use.observer.agent

Host metrics on macOSThe host source reports macOS memory as Activity Monitor’s Memory Used, and network throughput is Linux only. See Probe types.

Forwarding flags to the embedded Bun runtime

The binary ships with a copy of the Bun runtime baked in. Runtime flags reach it via the BUN_OPTIONS environment variable, not via command-line arguments. Example:

BUN_OPTIONS="--smol" observer-agent

See bun.com/docs/bundler/executables for the full list of supported flags.

Upgrades

Run the download step again with the new VERSION, then restart the agent:

# Linux, systemd
sudo systemctl restart observer-agent
# macOS, launchd
launchctl kickstart -k gui/$(id -u)/use.observer.agent

Pin every installPin to an exact version in your install scripts and CI. New releases at github.com/useobserver/agent/releases. Roll forward deliberately; rollbacks are a one-line revert of the URL.

When to prefer DockerUse the Docker quickstart when your host already runs containers, when you want pinning via image tags, or when you want the agent isolated from the host’s user namespace. The binary path is the lightest install but offers fewer guardrails.

Quickstart

Concepts

Guides

Reference

Install from a release binary

Prerequisites

Steps

Forwarding flags to the embedded Bun runtime

Upgrades

​Prerequisites

​Steps

​Forwarding flags to the embedded Bun runtime

​Upgrades

Prerequisites

Steps

Forwarding flags to the embedded Bun runtime

Upgrades