Install on Docker

Run the published image with three environment variables.

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 value for PROMETHEUS_SERVER_URL. This variable is required: the agent exits at startup if it is unset. Set it to a Prometheus URL the host can reach. When the agent runs no Prometheus probes, a placeholder URL is acceptable, but the variable must be present.

Steps

Pull the image

docker pull ghcr.io/useobserver/agent:1.2.0

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

The image listens on port 10101 for the debug dashboard. PROMETHEUS_SERVER_URL is required: the agent exits at startup if it is unset. When the agent runs no Prometheus probes, set it to a placeholder URL rather than omitting it.

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.

Production deployments

For 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, binds the dashboard, and reads secrets from a .env file.

Pinning

Pin to an exact version (agent:1.2.0). Track new releases at github.com/useobserver/agent/releases and roll forward when ready.

services:
  observer-agent:
    image: ghcr.io/useobserver/agent:1.2.0
    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.2.0

[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.2.0
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.

Was this page helpful?