Observer Docs

The fastest path to a running agent. Suitable for a development host, a single VM, or a quick proof of concept.

Prerequisites

Docker installed.
An agent key from the Observer console (Agents > Add agent). The key is shown once; copy it before navigating away.
A Prometheus URL the host can reach, 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

Pull the image

docker pull ghcr.io/useobserver/agent:1.7.3

Run the container

docker run -d \
  --name observer-agent \
  --restart unless-stopped \
  -v observer-agent-buffer:/data \
  -e BUFFER_PATH=/data/observer-agent-buffer.db \
  -e AGENT_KEY=obs_live_... \
  -e CLOUD_SERVER_URL=https://use.observer \
  -e PROMETHEUS_SERVER_URL=http://prometheus:9090 \
  ghcr.io/useobserver/agent:1.7.3

The observer-agent-buffer volume holds the local queue, so readings queued during a cloud outage survive the container being recreated. Agent images 1.6.0 and later set BUFFER_PATH to this path by default. Drop the PROMETHEUS_SERVER_URL line when the agent runs no Prometheus probes.

Confirm the connection

Check the logs with docker logs -f observer-agent: the agent logs Successfully fetched metric definitions once it reaches the cloud (typically within 30 seconds). The debug dashboard binds to the container’s loopback, so publishing port 10101 alone does not reach it; see Read the agent dashboard to expose it.The Agents page in the console marks the agent as running within 90 seconds.

Production deploymentsFor multi-host or cluster deployments, see Install on Kubernetes. The systemd wrap below works for bare-metal Linux hosts that don’t run k8s. The Docker path is recommended only for single-host development.

Compose

For a Compose-driven setup, use the snippet below. It pins the image, keeps the local queue on a volume, and reads secrets from a .env file.

PinningPin to an exact version (agent:1.7.3), or to the major tag (agent:1) to pick up 1.x releases as they ship. latest moves only when a release is tagged. Track new releases at github.com/useobserver/agent/releases and roll forward when ready.

docker-compose.yml

services:
  observer-agent:
    image: ghcr.io/useobserver/agent:1.7.3
    container_name: observer-agent
    restart: unless-stopped
    env_file: [.env]
    environment:
      BUFFER_PATH: /data/observer-agent-buffer.db
    volumes:
      - observer-agent-buffer:/data

volumes:
  observer-agent-buffer:

.env

AGENT_KEY=obs_live_...
CLOUD_SERVER_URL=https://use.observer
PROMETHEUS_SERVER_URL=http://prometheus:9090

Run under systemd

Use this when the host is bare-metal Linux without k8s and you want Docker isolation alongside systemd auto-restart + journal log capture. Prefer Install from a release binary when Docker isn’t a hard requirement. Fewer moving parts.

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 docker pull ghcr.io/useobserver/agent:1.7.3

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

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

[Service]
Type=simple
EnvironmentFile=/etc/observer-agent.env
ExecStartPre=-/usr/bin/docker rm -f observer-agent
ExecStart=/usr/bin/docker run --rm --name observer-agent \
  --network host \
  -v observer-agent-buffer:/data \
  -e BUFFER_PATH=/data/observer-agent-buffer.db \
  --env-file /etc/observer-agent.env \
  ghcr.io/useobserver/agent:1.7.3
ExecStop=/usr/bin/docker stop observer-agent
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now observer-agent
journalctl -u observer-agent -n 50 --no-pager

Why host networking--network host lets the agent reach Prometheus and probe targets bound to the host’s loopback or its private interface. If your targets sit on a Docker bridge instead, drop the host-network flag and use the bridge IP.

Quickstart

Concepts

Guides

Reference

Install on Docker

Prerequisites

Steps

Compose

Run under systemd

​Prerequisites

​Steps

​Compose

​Run under systemd

Prerequisites

Steps

Compose

Run under systemd