Skip to content
Docs

Install with Docker

On this page
  1. Run the agent
  2. Docker Compose
  3. Several agents on one host
  4. Health checks and container platforms
  5. Settings
  6. Manage the container

The agent is published as the Docker image onagreio/agent. It needs its token and outbound access, nothing else: no volume, no exposed port.

x64 only

The image is built for linux/amd64. On ARM64 hosts, use the automatic installer or the Linux binary.

Run the agent#

Terminal
docker run -d \
    --name onagre-agent \
    --restart=always \
    --ulimit nofile=65536:65536 \
    -e "TOKEN=<YOUR_TOKEN>" \
    onagreio/agent
Option Why
--restart=always The agent restarts with Docker and after any failure.
--ulimit nofile=65536:65536 Lets the agent keep many checks open at once.
-e "TOKEN=…" The agent's token. Prefer --env-file with a file readable only by you, so the token stays out of your shell history.

The container reaches what the host's network reaches. To check services that listen on the host itself (localhost), add --network host.

Images are tagged with the agent version (for example onagreio/agent:2.8.4.112) and latest. Pin a version on production hosts so updates stay deliberate.

Docker Compose#

YAML
services:
  onagre-agent:
    image: onagreio/agent:latest
    restart: always
    env_file: ./onagre-agent.env     # TOKEN=<YOUR_TOKEN>
    ulimits:
      nofile: { soft: 65536, hard: 65536 }

The logs go to the container output: docker logs onagre-agent.

Several agents on one host#

The Linux installer runs one agent per machine. To run several agents on the same host — for example one per network or per environment — run one container per agent, each with its own token (create one agent per container in Onagre):

YAML
services:
  agent-prod:
    image: onagreio/agent:2.9.0.0
    restart: always
    env_file: ./agent-prod.env       # TOKEN=<TOKEN_OF_THE_PROD_AGENT>
  agent-staging:
    image: onagreio/agent:2.9.0.0
    restart: always
    env_file: ./agent-staging.env    # TOKEN=<TOKEN_OF_THE_STAGING_AGENT>

Never give the same token to two containers: the second one is refused (Another agent is already connected with this token).

Health checks and container platforms#

The agent serves /health, /ready and /status on port 27520 — see Health endpoints. They listen inside the container only by default (127.0.0.1): a Docker HEALTHCHECK run inside the container works as is, but probes from outside the container need HTTP_API_BIND=any.

On Kubernetes or a managed container platform (Scaleway Serverless Containers, Cloud Run, Azure Container Apps…):

  • set HTTP_API_BIND=any, then point the liveness probe at /health and the readiness probe at /ready;
  • the platform's PORT variable, when it sets one, is used by the agent;
  • keep exactly one instance running: no scale-to-zero — the agent holds a permanent connection to the Hub — and no second replica — a second instance with the same token is refused (Another agent is already connected with this token). Need two agents? Create two agents in Onagre;
  • no inbound route is needed: the endpoints are only for the platform's probes.

Settings#

Variable Default Purpose
TOKEN (required) The agent's token.
PORT 27520 Port of the health endpoints (a platform's own PORT takes precedence).
HTTP_API_BIND 127.0.0.1 any to accept probes from outside the container.
HTTP_API on 0 to turn the health endpoints off.
LOG_FORMAT text json to write the logs as compact JSON lines, for platforms that index JSON.

All settings: Agent configuration.

Manage the container#

Task Command
Logs docker logs -f onagre-agent
Restart docker restart onagre-agent
Update docker pull onagreio/agent:latest, then remove the container and run it again
Remove docker rm -f onagre-agent