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. A hostname works too (ip:play.example.com). The (ephemeral) reply includes the live status card from a verification poll — if the address is wrong you see an offline card with the reason right there, not five minutes later.
3. (Optional) Enable notifications — click 🔔 Post alerts in this channel right on that reply, or configure explicitly:

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

4. Share the public card — anyone can run it:

   /fivem-status
   

Setup asks the platform to authorize outbound HTTP to that IP for your Discord (SDK allow_host), so the caller must have Manage Server. Scheduled polls then run every 5 minutes; tune with /fivem-config poll_interval minutes:N (5–60, rounded up to a 5-minute tick).

Slash commands

Configuration

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

• Registered server — address (IPv4 or hostname), port, friendly name. Set via setup, removed via remove.
• Poll interval — How often the plugin fetches from the FXServer. Default 5 min, range 5–60 on 5-minute ticks (the platform's cron floor).
• Notification channel — Where transition / threshold messages post.
• Notification role — Optional role mention. Every alert is sent with allowed_mentions: {parse: []} plus the configured role whitelisted — nothing else can ping, and the server name is neutralized in the content as well.
• 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 — the platform fires a server-side cron (manifest.json → "cron": [{"spec": "*/5 * * * *", "name": "poll_tick"}]) every 5 minutes per install and routes it to @plugin.cron poll_tick, which only fetches when interval_minutes has elapsed since the last poll. Marketplace installs run in pool mode, where @plugin.schedule threads never start — this is the only scheduling path that works. An ephemeral dedup guard (inflight:poll) prevents overlapping workers from double-polling.
• Host authorization — proxy_domains_requested is fixed at publish time, so setup calls ctx.http.allow_host(address) (SDK ≥ 0.10.0) from the admin's slash interaction; the platform verifies the caller and that the host is public, then allows it for that Discord only. remove revokes it. Setup is self-verifying: only an explicit platform refusal blocks it, and the verification poll is the real test — if the proxy still refuses a new host the registration is rolled back with the reason, and /fivem-config show reports the authorization outcome (platform-approved / not supported by this platform version / unverified / never requested).
• 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.
• Public addresses only. IPv4: loopback, RFC1918, link-local (incl. 169.254.169.254 cloud metadata), multicast, broadcast, carrier-grade NAT, and reserved ranges are rejected at registration (finding B1 in AUDIT-REPORT.md). Hostnames: ASCII/punycode only, no IPv6 literals, and special-use / internal suffixes (localhost, .local, .internal, .lan, .corp, .test, …) are refused locally; the platform's allow_host then resolves the name and verifies it's public before the proxy will reach it.
• 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. The FXServer host itself is not in proxy_domains_requested (it can't be — it's per-install); it is authorized at setup time through the SDK's allow_host and scoped to the Discord that registered it.

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 tools/fake_host.py          # real plugin process + real SDK, fake host, fixture FXServer (offline)
python tools/fake_host.py --live   # same, polling a real public FXServer

The fake host speaks the runner's JSON-RPC protocol to __main__.py in pool mode and exercises the whole loop — setup with allow_host, cron routing to poll_tick, /fivem-status, both buttons, show, remove — under every platform-policy shape (approved / unsupported / refused / blocked). It is the closest thing to a production run that exists without a YourBot install; tests/test_e2e_protocol.py runs its fixture scenarios in the audit gate.

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 in --strict mode (validator warnings fail too — one of them, schedule_task_never_runs, is production-fatal) 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.