# Synapse-iDOCK Host Agent

A lightweight agent that runs on a Docker host, reads the local Docker socket,
and **pushes** container inventory + live metrics to Synapse-iDOCK. All traffic
is outbound — you never expose the Docker API (`2375`/`2376`) on the network.

This is the **recommended** way to bring hosts into iDOCK, especially when the
Docker daemon isn't reachable over TCP (the default on almost every host).

## How it works

```
   Docker host                                  Synapse-iDOCK server
 ┌───────────────┐   outbound HTTPS (Bearer)   ┌────────────────────┐
 │ idock-agent   │ ─── POST /agent/report ───▶ │  dashboard/metrics  │
 │  reads socket │ ◀── GET  /agent/commands ── │  dashboard/metrics  │
 │  runs commands│ ─── POST .../result ──────▶ │  webhooks           │
 └───────────────┘                             └────────────────────┘
```

1. The agent registers its host and its containers **appear on the dashboard
   automatically** (the bearer token is the trust boundary — no approval step).
2. Inventory + CPU/RAM/Net/Disk metrics flow in every report cycle.
3. **Start / Stop / Restart / Update / Logs** from the dashboard are queued and
   executed by the agent on its next poll.
4. Revoke the token under **API Tokens** to disconnect the host instantly.

## Easiest — copy the command from the UI

Open **Deploy Agent** in Synapse-iDOCK, click **Generate token**, and copy the
single command it shows. It's pre-filled with your server URL and token and pulls
the agent image straight from the iDOCK server (no registry needed):

```bash
curl -fsSL https://idock.example.com/agent/image.tar.gz | docker load && \
docker run -d --name idock-agent --restart unless-stopped \
  -e IDOCK_URL="https://idock.example.com" -e IDOCK_TOKEN="idk_xxxxxxxx" \
  -e IDOCK_AGENT_NAME="$(hostname)" -e IDOCK_AGENT_ID_FILE=/state/agent_id \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v idock_agent_state:/state \
  synapse-idock-agent:1.0.0
```

That's the whole install. The rest of this file is for alternative setups.

## Prerequisites

1. In the iDOCK UI, go to **Deploy Agent** (or **API Tokens**) and copy an `idk_…` token.
2. The host must have Docker running and outbound network access to the server.

## Option A — docker compose

From this `agent/` directory (or with the bundled `docker-compose.yml`):

```bash
IDOCK_URL=https://idock.example.com IDOCK_TOKEN=idk_xxxx docker compose up -d
```

## Option A2 — registry image

If you publish the image (`./build-image.sh ghcr.io/acme/synapse-idock-agent:1.0.0 --push`)
and set `IDOCK_AGENT_IMAGE` on the server, the Deploy Agent command becomes a plain
`docker run ghcr.io/acme/synapse-idock-agent:1.0.0 …` that `docker` auto-pulls.

> The socket is mounted **read-write** so the dashboard's Start/Stop/Update buttons
> work. Append `:ro` for monitoring only.

## Option B — run directly (systemd)

```bash
pip install -r requirements.txt

sudo tee /etc/systemd/system/idock-agent.service >/dev/null <<'EOF'
[Unit]
Description=Synapse-iDOCK Agent
After=docker.service
Requires=docker.service

[Service]
Environment=IDOCK_URL=https://idock.example.com
Environment=IDOCK_TOKEN=idk_xxxxxxxx
Environment=IDOCK_AGENT_NAME=%H
Environment=IDOCK_AGENT_ID_FILE=/var/lib/idock-agent/agent_id
ExecStart=/usr/bin/python3 /opt/idock-agent/idock_agent.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now idock-agent
```

## Configuration

| Variable | Default | Purpose |
|----------|---------|---------|
| `IDOCK_URL` | — (required) | Server base URL, e.g. `https://idock.example.com` |
| `IDOCK_TOKEN` | — (required) | Bearer token from **API Tokens** |
| `IDOCK_AGENT_NAME` | hostname | Friendly host name shown in iDOCK |
| `IDOCK_REPORT_INTERVAL` | `20` | Seconds between inventory reports |
| `IDOCK_COMMAND_INTERVAL` | `5` | Seconds between command polls |
| `IDOCK_AGENT_ID_FILE` | `./agent_id` | Where the stable agent id is stored |
| `IDOCK_VERIFY_TLS` | `true` | `false` to accept a self-signed server cert |

## Security

* Outbound-only: no inbound ports opened on the host.
* Authenticated with a revocable bearer token (revoke it in **API Tokens** to
  cut a host off instantly).
* The bearer token is the trust boundary — a host and its containers appear on the
  dashboard as soon as a valid token reports; revoke the token to remove access.
* Mount the Docker socket read-only for monitoring; read-write only if you want
  remote lifecycle control.
