Install on Docker

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 > New agent). The key is shown once; copy it before navigating away.
• A Prometheus URL the host can reach (only required if the agent will run Prometheus probes; HTTP / TCP / DNS / TLS-cert probes do not need it).

Steps

1. •

   Pull the image

   docker pull ghcr.io/useobserver/agent:1.0.4

2. •

   Run the container

   docker run -d \
     --name observer-agent \
     --restart unless-stopped \
     -p 10101:10101 \
     -e AGENT_KEY=obs_live_... \
     -e CLOUD_SERVER_URL=https://use.observer \
     -e PROMETHEUS_SERVER_URL=http://prometheus:9090 \
     ghcr.io/useobserver/agent:1.0.4

   The image listens on port 10101 for the debug dashboard. If the agent will not run Prometheus probes, omit PROMETHEUS_SERVER_URL.

3. •

   Confirm the connection

   Open http://<host>:10101 in a browser. The dashboard's Cloud panel shows a recent last_heartbeat_at timestamp once the agent has registered with the cloud (typically within 30 seconds).

   The Agents page in the console marks the agent as running within 90 seconds.

Compose

For a Compose-driven setup, use the snippet below. It pins the image, binds the dashboard, and reads secrets from a .env file.

services:
  observer-agent:
    image: ghcr.io/useobserver/agent:1.0.4
    container_name: observer-agent
    restart: unless-stopped
    env_file: [.env]
    ports:
      - "10101:10101"

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.0.4

[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 \
  --env-file /etc/observer-agent.env \
  ghcr.io/useobserver/agent:1.0.4
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