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

> [!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. Pull the image**

```bash theme={null}
docker pull ghcr.io/useobserver/agent:1.7.3
```

**2. Run the container**

```bash theme={null}
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](https://docs.use.observer/agent/concepts/local-queue.md), 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.

**3. 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](https://docs.use.observer/agent/guides/read-the-dashboard.md) to
expose it.

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

> [!NOTE]
>
> **Production deployments**
>
> For multi-host or cluster deployments, see
> [Install on Kubernetes](https://docs.use.observer/agent/quickstart/install-kubernetes.md). 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.

> [!NOTE]
>
> **Pinning**
>
> Pin 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](https://github.com/useobserver/agent/releases)
> and roll forward when ready.

```yaml title="docker-compose.yml" theme={null}
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:
```

```bash title=".env" theme={null}
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](https://docs.use.observer/agent/quickstart/install-binary.md)
when Docker isn't a hard requirement. Fewer moving parts.

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

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

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable --now observer-agent
journalctl -u observer-agent -n 50 --no-pager
```

> [!NOTE]
>
> **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.


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