Install from a release binary

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 > New agent).
• A reachable Prometheus URL (only required for Prometheus probes).

Steps

1. •

   Pick the binary for your platform

   Releases live at github.com/useobserver/agent/releases. Each release publishes five binaries plus a SHA256SUMS file.

   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

2. •

   Download and verify

   VERSION=1.0.4
   curl -fLO https://github.com/useobserver/agent/releases/download/agent-v${VERSION}/observer-agent-linux-x64
   curl -fLO https://github.com/useobserver/agent/releases/download/agent-v${VERSION}/SHA256SUMS
   shasum -a 256 -c SHA256SUMS --ignore-missing
   chmod +x observer-agent-linux-x64
   sudo mv observer-agent-linux-x64 /usr/local/bin/observer-agent

3. •

   Run

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

   The dashboard listens on http://localhost:10101. The console's Agents page marks the agent as running within 90 seconds.

4. •

   Run as a systemd service (optional)

   [Unit]
   Description=Observer agent
   Wants=network-online.target
   After=network-online.target
   
   [Service]
   Type=simple
   EnvironmentFile=/etc/observer-agent.env
   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

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

VERSION=1.0.4
curl -fLO https://github.com/useobserver/agent/releases/download/agent-v${VERSION}/observer-agent-linux-x64
chmod +x observer-agent-linux-x64
sudo mv observer-agent-linux-x64 /usr/local/bin/observer-agent
sudo systemctl restart observer-agent