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 up -d
docker compose logs -f

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 is FATAL by design — check AGENT_IDENTITY / AGENT_PASSWORD in .env and docker compose 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 (the tag + AGENT_VERSION in compose.yml are usually already bumped centrally), then:

docker compose pull
docker compose up -d

(Second agent on this box? Its compose.agent2.yml is not auto-discovered — upgrade it explicitly: docker compose --env-file .env-agent2 -f compose.agent2.yml pull && docker compose --env-file .env-agent2 -f compose.agent2.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 compose.yml.
Second agent on the same box: each agent needs its OWN credentials — copy compose.yml to compose.agent2.yml AND create a second env file (.env-agent2), then run it with docker compose --env-file .env-agent2 -f compose.agent2.yml up -d (plain docker compose up -d always operates on the first agent only — compose.agent2.yml is not auto-discovered, which is the safe direction). 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're not in the kit directory (`compose.yml` is auto-discovered only from the directory you run in). `cd` into the `onlyscans-agent-kit` clone, or use plain `docker logs onlyscans-agent` (the container itself is fine)
Upgraded from an older kit (`docker-compose.agent.yml`)?	The compose file was renamed to `compose.yml` — `git pull` removes the old one. Use plain `docker compose up -d` / `logs -f` from now on; your `.env` is untouched. If you EDITED the old tracked file (e.g. applied the host-network swap) `git pull` will refuse — restore it first (`git checkout -- docker-compose.agent.yml`), pull, then re-apply your change in an untracked `compose.override.yml` (auto-merged with `compose.yml`, so future pulls stay clean)
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

4.4 KiB Raw Blame History