Run a sensor

#Hardware

Anything Linux-capable works. A few combinations that people in the community have run for months:

• A spare Raspberry Pi 3 or 4 on a home network (port-forward recommended)
• A $5/month VPS at your cloud provider of choice
• An old laptop running Ubuntu Server in a closet
• A repurposed mini-PC or NAS with Docker installed

CPU and RAM requirements are modest: a single sensor comfortably fits in 512 MB of RAM and uses less than 1% of a Pi 4's CPU during normal activity.

#Docker install

One command on any Linux host with Docker:

docker run -d \
  --name boarnet-sensor \
  --restart unless-stopped \
  -p 2222:2222 \
  -p 2323:2323 \
  -e BOARNET_ENROLL_TOKEN=<your-token> \
  ghcr.io/Bino97/boarnet-sensor:latest

Ports 2222 and 2323 are the default SSH and Telnet honeypot ports. Expose additional ports if you want to catch more protocols — the container will accept them automatically.

#Verify the sensor is reporting

curl -H "Authorization: Bearer <your-token>" \
     https://api.boarnet.local/sensors/me

{
  "sensor_id": "mesh-xyz-42",
  "fleet": "mesh",
  "status": "reporting",
  "uptime_seconds": 3412,
  "events_ingested": 218,
  "tier_promoted_at": null
}

#Desktop app

Prefer a one-click install? The Tauri-based BoarNet Sensor app wraps the same container in a tray-icon GUI for macOS, Windows, and Linux desktops. UPnP negotiation is automatic for home networks.

#Enrollment

Enrollment tokens are minted from your account. Each token binds one sensor to one API key. Mint a token, paste it into the container (or the desktop app's enrollment screen), and your sensor is online.

1. Open the dev dashboard (or account page in production)
2. Mint an enrollment token for Participant tier
3. Paste into BOARNET_ENROLL_TOKEN
4. Optionally set BOARNET_CITY and BOARNET_COUNTRY if you want to override the auto-detected location (see below)
5. Start the container; it registers and begins reporting

Promotion to Participant happens after 48 hours of valid, unique telemetry. Low-traffic networks may take longer — the system looks for diversity, not volume.

#How location is determined

The map and the per-record sensor list show where each sensor is. That location is built from two sources, neither of which reads anything off your machine:

• Countryis derived at the ingestion API from the sensor's public IP — the same IP the network stack already exposes to any server it connects to. No probe, no query of the host.
• City is optional and self-declared at enrollment via BOARNET_CITY. Leave it unset and the record shows country only.

#Privacy boundary

The sensor is purpose-built to collect as little about you as possible while still being useful to the mesh. Everything the mesh learns about a sensor is listed below — if it's not here, we don't have it.

#Troubleshooting

#Sensor is online but not seeing traffic

Most likely your IP isn't reachable from the public internet. Confirm port forwarding is in place and run nc from another machine to verify.

#Sensor has been up 48 hours but isn't promoted

The promotion check looks for unique attacker signatures. If your network only sees the same scanner repeatedly, wait — real diversity arrives with time.