FiveLive

Live status and notifications for one FiveM/GTA RP server, delivered in Discord. A YourBot.gg plugin.

What it is

FiveLive lets a Discord server admin attach their community to a single FiveM server. After a one-time /fivem-config setup, the plugin polls the FXServer's public JSON endpoints (info.json, dynamic.json, players.json) on a schedule and surfaces the result. Anyone in the Discord can run /fivem-status for a live card with a 🔄 Refresh button that re-renders it in place; admins can opt into transition (online / offline) and threshold (player-count) notifications posted to a designated channel.

It is explicitly not a global FiveM search tool. The Cfx.re centralized API is locked and persistent player identifiers were removed from public responses in late 2024. FiveLive works with what's actually reachable: the single direct-HTTP-accessible server an admin chooses to track.

Preview

🟢 My Awesome RP Server
San Andreas • Roleplay • QBCore

Players      ███████░░░  64 / 128
Today (UTC)  ▁▂▂▃·▃▅▆█▇▆▅
Server       FXServer v7290 • OneSync: on • 200 resources
Tags         roleplay, whitelist, custom-cars
Locale       en-US               Peak today  92 players

Last polled: 2 min ago • Poll interval: 5 min

🔴 My Awesome RP Server
Server unreachable.
Reason: network_error

Last poll  14:32 UTC (47 min ago)
Last polled: 47 min ago • Poll interval: 5 min

Real Discord screenshots will land in docs/screenshots/ after the first production install.

Quick start

1. Install the plugin from the YourBot.gg marketplace.
2. Register your FiveM server (admin only):

   /fivem-config setup ip:203.0.113.42 name:My RP Server
   

   Port defaults to 30120; pass port:N to override.
3. Verify the registration worked:

   /fivem-status
   

4. (Optional) Enable notifications — click 🔔 Post alerts in this channel right on the setup confirmation, or configure explicitly:

   /fivem-config notify channel:#server-status enabled:true
   /fivem-config thresholds full_pct:90 half_drop:true
   

The first scheduled poll happens within one minute. Default poll interval is 5 minutes; tune with /fivem-config poll_interval minutes:N (1–60).

Slash commands

Configuration

All configuration lives in YourBot KV under schema-versioned keys. Seven tunables:

• Registered server — IP, port, friendly name. Set via setup, removed via remove.
• Poll interval — How often the plugin fetches from the FXServer. Default 5 min, range 1–60.
• Notification channel — Where transition / threshold messages post.
• Notification role — Optional role mention; FiveLive enforces allowed_mentions: {parse: []} on every dispatched message, so @everyone in a hostname can't accidentally ping.
• Full threshold (full_pct) — Percent of players_max that fires server_full (default 90). Crossing semantics: fires once on the poll where players_now first reaches the threshold; 30-min cooldown.
• Absolute full threshold (full_at) — An explicit player count that fires server_full, overriding full_pct. For servers that advertise a vanity sv_maxclients (e.g. 2000 while peaking ~20), where a percentage trigger is unreachable. Off by default; full_at:0 clears it back to full_pct mode.
• Half-drop (half_drop) — Opt-in server_below_half notification on transitions below half capacity. Off by default.

/fivem-config show displays everything in one ephemeral embed.

How it works

• One server per Discord — the plugin's KV is namespaced per (server, plugin), and FiveLive stores exactly one server registration.
• Background polling — @plugin.schedule(60) ticks every minute and only actually fetches when interval_minutes has elapsed since the last poll. An ephemeral dedup guard (inflight:poll) prevents worker-restart double-fires.
• Three endpoints, sequential — info.json and dynamic.json are critical (failure → offline); players.json is best-effort (failure → empty player list, status still online). A 12-second wall-clock budget caps each poll.
• Transition + threshold events — server_online / server_offline (3-poll streak) / server_full / server_below_half. Each event type has its own KV-backed cooldown (notify:last:{event}); the notify_dedup audit gate in tools/run_audit.py statically enforces that every notification call site has a cooldown check in the preceding 20 lines.
• Hardened against malicious server data — FiveM color codes, NFKC-normalization, bidi-strip, markdown-strip, @everyone / @here neutralization, depth-bomb JSON guard (64-level cap), and Cloudflare-interstitial detection all live in the poll → embed path.

For the full design rationale — alternatives considered and rejected for every major decision — read ARCHITECTURE.md.

Limitations

These are intentional, not bugs:

• One server per Discord. Adding a second registration is rejected. Multi-server support is a v1.2.x candidate.
• IPv4 only. DNS hostnames are not yet accepted at setup. Resolve manually for now.
• Public IPv4 only. Loopback, RFC1918, link-local (incl. 169.254.169.254 cloud metadata), multicast, broadcast, carrier-grade NAT, and reserved IPv4 ranges are rejected at registration. See finding B1 in AUDIT-REPORT.md.
• Cloudflare-fronted servers are unreachable. Many production RP servers proxy through Cloudflare and don't expose the direct JSON endpoints. FiveLive surfaces a specific proxied_no_json reason. See RUNBOOK.md scenario S1b.
• No cross-server data, no player-name search. Cfx.re's centralized API is locked and persistent player identifiers were removed in late 2024. Not solvable from within the plugin.
• Notifications can't replay missed events. If the configured channel is deleted during an outage, that outage's server_offline event is dropped.

The full "What's deferred" inventory lives in AUDIT-REPORT.md.

Privacy & security

FiveLive declares four YourBot capabilities, all Safe-tier (no install-time consent prompt beyond defaults):

• interaction:respond — answering slash commands
• storage:kv — registration, status snapshots, history (~18 keys steady state)
• proxy:http — outbound HTTP to the FXServer JSON endpoints
• discord:send_message — posting notifications to the admin-chosen channel

No storage:sql, no discord:delete_message, no discord:manage_roles. No Risky or Dangerous tier capabilities.

Data the plugin stores: the registered server's IP/port/name, periodic player counts (15-min buckets, 7-day retention), and configuration settings. Player names from players.json are stored in status:current (1-hour TTL) only — there is no long-term per-player tracking, because FiveM no longer exposes persistent identifiers.

The YourBot sandbox runs at 64 MB / 0.25 vCPU with --network none (only the SDK's ctx.http proxy reaches the outside), read-only root, ephemeral /tmp, and an empty environment. The plugin cannot read secrets from env, write to disk, or open raw sockets.

Development

git clone https://github.com/<owner>/fivelive.git
cd fivelive
pip install pytest        # only test dep; production is stdlib-only
python -m pytest tests/ -q
python tools/run_audit.py

Python is pinned by .python-version (3.14). The audit script runs nine gates: manifest, imports, no_eval, todo_markers, plugin_run, pytest, bundle, notify_dedup, platform_validator. All nine must exit green before a change is mergeable. The last gate runs the SDK's vendored upload validator against the built fivelive.zip and needs yourbot-sdk installed (pip install yourbot-sdk).

Project handoff doc for AI agents continuing work: CLAUDE.md.

Audit trail

These are public on purpose. Anyone considering installing FiveLive should be able to read exactly how it was built and where its limits are:

• AUDIT-REPORT.md — R0 / R2 findings with severity, probe, fix, files, status. The B1 SSRF defense + four MAJOR fixes from v1.1.0 are all documented here.
• SDK-ASSUMPTIONS.md — every place the code defends against undocumented SDK behavior, with a 10-step pre-deploy probe order.
• CHANGELOG.md — version history in Keep-a-Changelog format.
• RUNBOOK.md — 10 operational scenarios (upstream down, OOM, Cloudflare, schema migration, rollback, etc.).
• ARCHITECTURE.md — design decisions with alternatives considered and rejected.

Credits

• YourBot.gg platform — the sandboxed Discord plugin runtime FiveLive targets (formerly MMO Maid).
• Cfx.re / FiveM — the modification framework whose servers FiveLive polls.
• Keep a Changelog — changelog format.