Metadata-Version: 2.4
Name: wg-flow-agent
Version: 0.1.0
Summary: Open-source infrastructure inventory agent for wg-flow
Author: WaveGrid
License: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Dynamic: license-file

# wg-flow-agent

Open-source Python CLI that collects infrastructure inventory and pushes snapshots to [wg-flow](https://gitlab.com/wg-flow).

Credentials stay on your infrastructure — only normalized resource metadata is sent to the platform.

**License:** Apache-2.0 — see [LICENSE](LICENSE).

## Requirements

- Python 3.12+
- Tenant API token (`wgf_...`) from wg-flow workspace settings (owner)
- Provider credentials in the YAML config (never sent to wg-flow)

## Install

```bash
pip install -e .
pip install -e ".[dev]"   # tests / lint
```

The agent ships **without bundled provider plugins**. Install from the wg-flow marketplace:

```bash
wg-flow-agent plugin marketplace list
wg-flow-agent plugin install prometheus
wg-flow-agent plugin install proxmox
wg-flow-agent plugin list
```

Reference packages: `wg-flow-plugin-prometheus`, `wg-flow-plugin-proxmox`.

## Configuration

All agent settings live in YAML. Copy `config.example.yaml` to `wg-flow-agent.yaml` (or edit `config.docker.yaml` for Docker). Env vars do **not** override tenant/token/plugins.

```yaml
tenant_id: "..."
tenant_token: "wgf_..."
api_url: "http://localhost/api/v1"

agent:
  name: "agent-01"
  host: "node-1"

scheduler:
  sync_interval_seconds: 300   # default / heartbeat; minimum 300

plugins: {}
# After plugin install:
# plugins:
#   prometheus:
#     enabled: true
#     sources:
#       - id: prod
#         url: "https://prometheus.example"
#         sync_interval_seconds: 300
```

Optional UI toggles (Compose / process env only):

| Variable | Default | Description |
|----------|---------|-------------|
| `WGFLOW_UI_ENABLED` | `false` | Start UI with the scheduler |
| `WGFLOW_UI_HOST` | `0.0.0.0` (Docker) / `127.0.0.1` (CLI) | Bind address |
| `WGFLOW_UI_PORT` | `8765` | UI port |

`WGFLOW_CONFIG` is the YAML path **inside** the container. `WGFLOW_CONFIG_FILE` is the host bind path in Compose.

## CLI

```bash
wg-flow-agent run          # scheduler; optional --ui
wg-flow-agent sync         # one-shot collect + POST /sync/
wg-flow-agent dry-run      # collect, print JSON, no POST
wg-flow-agent status
wg-flow-agent ui           # http://127.0.0.1:8765
wg-flow-agent plugin list | marketplace list | install <name> | uninstall | update
```

`run` syncs on start, then each plugin **source** on its own `sync_interval_seconds` (default/min **300** s). Due sources are coalesced into one `POST /sync/`. YAML changes (including UI Save) apply on the next scheduler tick — no container restart for config.

## Docker

The image **bakes in** Python and the UI. There is no source bind-mount. After any code change: **rebuild**.

### Customer infra → SaaS

```bash
# Edit config.docker.yaml — tenant_token, api_url, plugins
docker compose up -d --build
docker compose logs -f agent
```

### Local dev against wg-flow-infra

The main stack must be up (`cd ../wg-flow-infra && ./scripts/dev-up.sh`). Then from this repo (joins external network `wgflow-net`; hostname `traefik` only resolves there):

```powershell
# Windows
.\scripts\dev-up.ps1      # scheduler + UI :8765
.\scripts\dev-ui.ps1      # UI only
.\scripts\dev-down.ps1
```

Set `config.docker.yaml`: `api_url: http://traefik/api/v1` and a valid `tenant_token`.

One-shot / CLI in the image:

```bash
docker compose run --rm agent wg-flow-agent sync
docker compose run --rm agent wg-flow-agent status
docker compose run --rm --build --service-ports agent wg-flow-agent ui --host 0.0.0.0 --port 8765
```

UI: **http://localhost:8765**
