dev_arc_aws/agent/README.md

# ArchNest Docker monitoring agent

A small push agent that reports this host's Docker containers to ArchNest. See
the design in [`docs/docker-agent-monitoring.md`](../docs/docker-agent-monitoring.md).

It is **monitoring only** — it pushes data outbound to ArchNest and never
receives or runs commands. Container management stays on ArchNest's
Docker-over-SSH / Docker API paths.

## Requirements

`bash`, `docker`, `curl`, `jq`. Install `jq` if missing:

```bash
# Debian/Ubuntu
sudo apt-get install -y jq
# RHEL/Alma/Rocky
sudo dnf install -y jq
# Alpine
sudo apk add jq
```

The user running the agent must be able to run `docker` (in the `docker` group
or via root).

## Install

1. Copy the script onto the VM and make it executable:

   ```bash
   sudo install -m 0755 archnest-docker-agent.sh /usr/local/bin/archnest-docker-agent
   ```

2. Create the config file (keep it root-only — it holds the token):

   ```bash
   sudo mkdir -p /etc/archnest
   sudo tee /etc/archnest/agent.env >/dev/null <<'EOF'
   ARCHNEST_URL=http://<archnest-mesh-ip>:4000
   ARCHNEST_AGENT_TOKEN=<the shared token, same as the backend>
   ARCHNEST_HOST_ID=proxmox-vm-1
   # ARCHNEST_HOSTNAME=docker01   # optional; defaults to `hostname`
   EOF
   sudo chmod 600 /etc/archnest/agent.env
   ```

   `ARCHNEST_URL` must point at the ArchNest backend over your **mesh / private
   network**, never a public address — the ingest endpoint is protected only by
   the shared token at the application layer.

3. Run it once to verify:

   ```bash
   sudo archnest-docker-agent
   # -> "reported N container(s) as 'proxmox-vm-1' (HTTP 200)"
   ```

## Schedule it (pick one)

Report interval should be **shorter than the backend's stale window**
(`ARCHNEST_AGENT_STALE_MS`, default 90s). 30s is a good default.

### Option A — cron (every minute; simplest)

```cron
* * * * * root /usr/local/bin/archnest-docker-agent >/dev/null 2>&1
```

(cron's finest granularity is 1 minute; raise `ARCHNEST_AGENT_STALE_MS` to e.g.
150000 on the backend if you use a 1-minute cron.)

### Option B — systemd service + timer (recommended; supports 30s)

`/etc/systemd/system/archnest-docker-agent.service`:

```ini
[Unit]
Description=ArchNest Docker monitoring agent
After=docker.service
Wants=docker.service

[Service]
Type=oneshot
EnvironmentFile=/etc/archnest/agent.env
ExecStart=/usr/local/bin/archnest-docker-agent
```

`/etc/systemd/system/archnest-docker-agent.timer`:

```ini
[Unit]
Description=Run ArchNest Docker monitoring agent every 30s

[Timer]
OnBootSec=30
OnUnitActiveSec=30
AccuracySec=5s

[Install]
WantedBy=timers.target
```

Enable:

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now archnest-docker-agent.timer
sudo systemctl list-timers archnest-docker-agent.timer   # confirm scheduling
journalctl -u archnest-docker-agent.service -n 20         # see last run output
```

## Backend configuration

The backend must have `ARCHNEST_AGENT_TOKEN` set (the same value as the agent).
If it is unset, the ingest endpoint is disabled and returns HTTP 503. Optional:
`ARCHNEST_AGENT_STALE_MS` (default 90000) controls when a host is shown stale.

## Security notes

- The token is a credential — treat `/etc/archnest/agent.env` as sensitive
  (`chmod 600`, root-owned).
- The agent masks env var values whose key matches
  `PASS|SECRET|TOKEN|KEY|PRIVATE|CREDENTIAL` before sending; the full values
  never leave the VM.
- Expose the ArchNest ingest endpoint on the mesh only, not the public internet.