Install the agent

The agent runs on your infrastructure. You do not need git or GitLab access.

The default path is Docker Hub. If you cannot use Docker, download the Python wheel from Releases.

The CLI command is still wg-flow-agent.

Requirements

• Docker Engine + Compose v2 or Python 3.12+
• A tenant API token (wgf_…) from the console — Connect

You do not need the full WaveGrid stack on the agent host. Compose, config, the wheel, and version history live on Releases.

Docker (recommended)

Create a directory and put docker-compose.yml and config.yaml there. Copy the blocks below or download a version from Releases.

mkdir agent && cd agent

docker-compose.yml with the :latest tag (pin a version from Releases):

services:
  agent:
    image: wavegrid/agent:latest
    container_name: agent
    environment:
      WGFLOW_CONFIG: /etc/wg-flow-agent/config.yaml
      WGFLOW_PLUGINS_DIR: /var/lib/wg-flow-agent/plugins
      WGFLOW_INSTALLED_PLUGINS: /var/lib/wg-flow-agent/installed_plugins.json
      WGFLOW_UI_ENABLED: "false"
      WGFLOW_UI_HOST: "0.0.0.0"
      WGFLOW_UI_PORT: "8765"
    ports:
      - "8765:8765"
    volumes:
      - ./config.yaml:/etc/wg-flow-agent/config.yaml
      - agent_data:/var/lib/wg-flow-agent
    restart: unless-stopped
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "wg-flow-agent plugin list >/dev/null && test -f /tmp/wg-flow-agent.last-sync",
        ]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 120s

volumes:
  agent_data:

In config.yaml set tenant_id, tenant_token, and api_url from the console — Connect.

docker compose up -d
docker compose logs -f agent

Docker pulls wavegrid/agent:latest from Docker Hub. The container syncs immediately, then on a schedule (minimum 5 minutes per source).

Local UI (private network only) — in the same environment block set WGFLOW_UI_ENABLED: "true" and rerun docker compose up -d. Open http://127.0.0.1:8765. Do not publish :8765 — the UI has no password.

Plugins:

docker compose exec agent wg-flow-agent plugin marketplace list
docker compose exec agent wg-flow-agent plugin install proxmox

pip (no Docker)

Python 3.12+. Download the wheel for the version you want from Releases and install it in a venv:

python3.12 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install ./wg_flow_agent-0.1.0-py3-none-any.whl

Copy config.yaml from the same page, fill in the fields, then:

export WGFLOW_CONFIG="$PWD/config.yaml"
wg-flow-agent run            # scheduler
wg-flow-agent run --ui       # + UI on 127.0.0.1:8765
wg-flow-agent sync           # one-shot, no daemon

Next

1. Connect the workspace — token and api_url.
2. Install plugins.
3. In the app: Inventory → Agents — status online.