Only Scans — remote agent install kit

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/noctools/onlyscans-agent-kit.git
cd onlyscans-agent-kit
cp .env.agent.example .env
# edit .env: AGENT_IDENTITY / AGENT_PASSWORD
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 to PocketBase … — that's it. (The agent's location is carried by its central record; nothing local participates.) 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: each agent needs its OWN credentials — copy the compose file AND create a second env file (.env-agent2), then run it with docker compose --env-file .env-agent2 -f docker-compose.agent2.yml up -d. In the copy, change the project name: and container_name (and WORKER_HEALTH_PORT under host networking) per the comments in the file. Two agents sharing one .env would share one auth record — unsupported and silently wrong.
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
`no configuration file provided: not found`	You ran a follow-up `docker compose logs`/`ps` without `-f docker-compose.agent.yml` — the kit's compose file has a non-default name, so it isn't auto-discovered. Re-run with `-f docker-compose.agent.yml`, or use plain `docker logs onlyscans-agent` (the container itself is fine)
Container exits ~1 s after start	Bad `AGENT_IDENTITY` or `AGENT_PASSWORD` — 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

3.7 KiB Raw Blame History