> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# Install from a release binary

> Download a single-file executable from GitHub Releases and run it directly, under systemd on Linux, or under launchd on macOS. 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** > **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.

> [!NOTE]
>
> **Proxies, private CAs and restricted egress**
>
> If 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](https://docs.use.observer/agent/guides/restricted-networks.md).

## Steps

**1. Download and verify**

Releases live at
[github.com/useobserver/agent/releases](https://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:

```bash theme={null}
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.

**2. 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:

```bash theme={null}
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.

**3. Run**

```bash theme={null}
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).

**4. Linux: run as a systemd service (optional)**

```ini title="/etc/systemd/system/observer-agent.service" theme={null}
[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
```

```bash theme={null}
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`.

**5. 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.

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
launchctl bootout gui/$(id -u)/use.observer.agent
```

> [!NOTE]
>
> **Host metrics on macOS**
>
> The `host` source reports macOS memory as Activity Monitor's **Memory
> Used**, and network throughput is Linux only. See
> [Probe types](https://docs.use.observer/agent/reference/probe-types.md#notes-on-specific-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:

```bash theme={null}
BUN_OPTIONS="--smol" observer-agent
```

See
[bun.com/docs/bundler/executables](https://bun.com/docs/bundler/executables#runtime-arguments-via-bun_options)
for the full list of supported flags.

## Upgrades

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

```bash theme={null}
# Linux, systemd
sudo systemctl restart observer-agent
# macOS, launchd
launchctl kickstart -k gui/$(id -u)/use.observer.agent
```

> [!NOTE]
>
> **Pin every install**
>
> Pin to an exact version in your install scripts and CI. New
> releases at
> [github.com/useobserver/agent/releases](https://github.com/useobserver/agent/releases).
> Roll forward deliberately; rollbacks are a one-line revert of the
> URL.

> [!NOTE]
>
> **When to prefer Docker**
>
> Use the [Docker quickstart](https://docs.use.observer/agent/quickstart/install-docker.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.