Listener nodes
A listener sends real sensor snapshots to your online account. It needs Python 3, internet access and a node code—not the Go engine.
Set this up with an AI agent ↗
Limits and cadence
- Free: 3 devices. Premium: 12 devices.
- Passive listeners and Auto mode: 30 minutes. Manual scans normally have a 5-minute cooldown. Node boosts affect manual eligibility, never the passive floor.
- Passive scans wait at least 1800 seconds, and honor longer
next_snapshot_inorretry_aftervalues. Give each device its own code.
1. Create a node
Sign in and open Nodes. Create a named device and save its code privately. In the standalone app, paste it into World → Link account; your name, email, plan and device details confirm the account.
2. Run one listener cycle
Store WB_NODE_TOKEN in your environment or a private local environment file first. Do not paste it into public scripts or logs.
curl -fsSL https://wavebeasts.com/download/wavebeast-node.py -o wavebeast-node.py
# WB_NODE_TOKEN is already set privately in this shell.
WB_SITE=https://wavebeasts.com WB_ONCE=1 python3 wavebeast-node.pyThe listener reads Wi-Fi via nmcli where available. Other operating systems may need a sensor adapter. Verify that the log reports real signals and a successful result; a zero exit code alone does not prove the server accepted it.
3. Keep it running
WB_SITE=https://wavebeasts.com python3 -u wavebeast-node.pyFor background operation, use a per-user service. Example Linux unit at ~/.config/systemd/user/wavebeast-node.service, assuming the script is at ~/.local/share/wavebeast-node/wavebeast-node.py:
[Unit]
Description=WaveBeasts listener
After=network-online.target
[Service]
EnvironmentFile=%h/.config/wavebeast-node/node.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/usr/bin/python3 %h/.local/share/wavebeast-node/wavebeast-node.py
Restart=on-failure
RestartSec=15
[Install]
WantedBy=default.targetThe environment file contains WB_SITE=https://wavebeasts.com and your WB_NODE_TOKEN; restrict it to your user with mode 600. Confirm the Python path on your machine.
systemctl --user daemon-reload
systemctl --user enable --now wavebeast-node
systemctl --user status wavebeast-node
journalctl --user -u wavebeast-node -n 20 --no-pager
# Stop and disable:
systemctl --user disable --now wavebeast-nodeUser services may stop at logout unless lingering is configured. macOS uses launchd and Windows uses Task Scheduler; the AI setup prompt handles those differences.
Troubleshooting
| Result | Meaning / action |
|---|---|
| 200 / accepted | Success. A beast, resources or nothing are all valid outcomes. |
| 403 | Invalid/revoked code. Generate a current code and relink. |
| 429 | Wait for retry_after; do not increase submission speed. |
| Zero signals | Check nmcli/sensor permissions or add a real adapter. |
| Connection failure | Check internet access and WB_SITE. The listener retries at its fallback interval. |
Check and update your nodes
The Nodes page shows reported versions, their report times, and available updates. “Version not reported” means you should check that device; it does not mean it is current. Custom integrations remain supported and are not compared against official releases.
For the Python listener, stop its service, download the current script, replace the script at the path in your service's ExecStart, and restart the service. Preserve its token, environment settings and state directory. It reports its version on startup without scanning.
For an engine or app, install the current build from Download, preserving its database. The local GUI footer shows the installed version and offers “Check for updates”. Offline checks never stop local play.
Supported clients receive update prompts. Official engines older than 0.12.15 and listeners older than 1.1.0 (including unreported official versions) must update before scanning online. Updates are never installed automatically; existing collections, custom integrations and offline local play remain available. The account service separately enforces the 30-minute passive interval for recognized listeners and submissions marked scan_mode: "auto". Custom clients should identify themselves with client.id and client.app_v.
Node health dashboard
The Nodes page and linked app’s World tab separate last heard, last successful scan, last attempt and next attempt. Cards show installed versions, reported sensor categories and recent failures. A waiting node is distinct from a disconnected node. Clients without heartbeats show an unknown online status rather than being labeled offline.
Listener 1.2.0 sends a lightweight heartbeat every two minutes while waiting. The standalone engine does the same while running and using an account host. Heartbeats do not read sensors, consume cooldowns or grant rewards. Passive scans still run at least 30 minutes apart. A heartbeat more than three expected intervals old (at least five minutes) marks a reporting node offline; a suspended phone can therefore appear offline until it resumes.