Installing the Site Collector

↩ Getting Started

The Site Collector is a lightweight container you run on-premises at each site. It reaches the devices, servers, and services on that site's local network and reports back to JOATOS. It only makes outbound connections, so no inbound firewall rules are needed.

Before you start

• A Linux host at the site with Docker installed, able to reach your JOATOS API over HTTPS.
• Administrator access to JOATOS (to register the collector and download the installer).
• The host should be on, or able to route to, the subnets you want to monitor.

Step 1 — Register the collector

1. Go to Settings → Site Collectors.
2. Register a new collector. JOATOS generates a collector token.
3. Copy the token now — it's shown only once.

Step 2 — Download the installer

1. Go to Settings → Downloads.
2. On the Site Collector card, select Download installer (Linux/macOS).
3. This downloads site-collector-installer.sh, with your API address already built in.

Step 3 — Run the installer

Copy the installer to the Linux host and run it, passing your collector token:

bash site-collector-installer.sh <your-collector-token>

The installer pulls the collector image and starts it as a Docker container that restarts automatically. Behind the scenes it runs the container with host networking and raw-socket access so that ICMP (ping) monitoring works:

docker run -d \
  --name joatos-site-collector \
  --restart unless-stopped \
  --network host \
  --cap-add NET_RAW \
  -e API_URL="https://your-joatos-api" \
  -e AGENT_TOKEN="<your-collector-token>" \
  ghcr.io/subzeroau-rgb/joatos-site-collector:latest

Important: --network host and --cap-add NET_RAW are required. Without them, ICMP monitoring silently stops working and the collector may report container IDs instead of the host's real name and IP.

Step 4 — Assign sites

Back in JOATOS, assign one or more sites to this collector. From then on, all scanning and monitoring for those sites runs from this collector on your local network.

How it behaves

• The collector sends a heartbeat roughly every 30 seconds, reporting its status and picking up work (device polls, ICMP checks, discovery scans).
• It manages its own schedule — there's no separate queue server to run.

Configuration reference

The installer sets these for you; you rarely need to change them.

Notes & tips

• One collector per site. The collector image is public, so no registry login is required.
• The token is scoped to this collector and its assigned sites, and is stored hashed on the server — keep the copy you saved safe.

Related

• Creating your first site
• Installing the Endpoint Agent
• Running your first discovery scan