This repo installs a remote scan agent for the Only Scans platform on a docker host at your site. The agent is a location-labelled scanner: it logs into the central instance with its own credentials, picks up scans queued for your location, and reports results back.

The agent is inert without centrally-provisioned credentials — this repo contains no secrets.

What you get from Sam (central operator)

An agent username (e.g. chch-1)
The password shown once at agent creation
Your location name (e.g. chch-office)

Prerequisites

Docker + the docker compose plugin
Egress to scan-api.noctools.nz:443 (the central API, TLS)
Network reachability to the scan targets for your site — see "Host-network variant" below if you need ARP-level LAN discovery
~512 MB RAM for the container

Install

git clone https://gitea.noctools.nz/sam/onlyscans-agent-kit.git
cd onlyscans-agent-kit
cp .env.agent.example .env
# edit .env: AGENT_IDENTITY / AGENT_PASSWORD / AGENT_LOCATION
docker compose -f docker-compose.agent.yml up -d
docker logs -f onlyscans-agent

The worker image pulls anonymously — no docker login required.

Expected log lines on a healthy start: authenticated … agent <name>: AGENT_LOCATION "<loc>" validated. A rejected password or unknown location name is FATAL by design — check the values in .env and docker compose -f docker-compose.agent.yml up -d --force-recreate.

Verify centrally: Sam confirms the agent flips online on the central /agents page within ~90 s, then queues a pinned test scan against your location — claimed_by should show the agent username.

Upgrades

The compose file pins an image tag. To upgrade: git pull this repo, bump the tag + AGENT_VERSION in docker-compose.agent.yml if Sam hasn't already, then:

docker compose -f docker-compose.agent.yml pull
docker compose -f docker-compose.agent.yml up -d

The agent re-authenticates and resumes polling.

Options

Host-network variant (scan the site LAN directly, ARP-level discovery, non-routed subnets): swap the service to network_mode: host per the commented block in docker-compose.agent.yml.
Second agent on the same box: copy the compose file, change the project name: and container_name (and WORKER_HEALTH_PORT under host networking) per the comments in the file.
CVE matching (optional): fill CVE_MATCH_API + CVE_MATCH_TOKEN in .env only if Sam provides them. Without it, scans complete normally with the CVE stage skipped.

Troubleshooting

Symptom	Meaning
Container exits ~1 s after start	Bad `AGENT_PASSWORD` or unknown `AGENT_LOCATION` — fatal by design; fix `.env` and recreate
Agent shows offline centrally (`/agents`)	Container down, or no egress to `scan-api.noctools.nz:443` — check `docker logs onlyscans-agent`
Scans stay queued	Agent online but for a different location, or targets unreachable from the container's network — try the host-network variant