Install from a release binary
Download a single-file executable from GitHub Releases. No runtime install required on the host.
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 value for
PROMETHEUS_SERVER_URL. This variable is required: the agent exits at startup if it is unset. Set it to a reachable Prometheus URL. When the agent runs no Prometheus probes, a placeholder URL is acceptable, but the variable must be present.
Steps
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 |
Download and verify
VERSION=1.2.0
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
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.
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.2.0
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
Pin every install
Pin 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 Docker
Use 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.