ForgeGuard website pairing · ForgeCraft Wiki

Pairing connects one Minecraft server to one server workspace on a ForgeGuard website. After that, the members of that workspace can see the server's players, inventories, evidence and settings and act on them within the limits the server owner sets. Pairing needs both a website owner and explicit approval inside Minecraft; neither side can complete it alone.

Before linking

The server runs the modern ForgeGuard core (0.5.0-alpha.1 or later) on Paper with PacketEvents. The universal loader's portable staff-only fallback cannot pair.
You have an account on the ForgeGuard website and have created a server workspace for this server (Your servers → Add a server). You are an owner of that workspace.
In Minecraft you have forgeguard.staff and forgeguard.link.
The server can make outbound HTTPS requests to the website. Nothing needs to reach the server.
Decide what the website may do. In plugins/ForgeGuard/config.yml:

web:
  allow-config: true          # change detection settings and reload them
  allow-moderation: true      # freeze, kick, ban and unban
  allow-inventory-view: true  # read inventories and Ender Chests
  allow-inventory-edit: true  # change inventories and Ender Chests
  notify-staff: true          # tell /fg alerts subscribers about website inventory edits
  blocked-items: [command_block, structure_block, jigsaw, debug_stick]   # never created from the web

Run /fg reload after changing these. The approval screen shows the current list.

Connect

Point the plugin at the website, once: /fg link site https://your-site.example. The workspace's Server setup page shows the exact command. The address can also go in link.site-url (restart after a YAML change).
Open /fg menu → Link web console → Generate pairing code. The ten-character code expires after ten minutes. From the console, /fg link code works too.
On the website, open the workspace's Server setup and enter the code. The website now shows Waiting for Minecraft approval. A code is single use, even if the claim fails.
Back in Link web console, check the website address and the claiming e-mail, and read what will be allowed. Approve only if it is the account you expect. From the console: /fg link shows the claim ID, then /fg link approve <claim-id>.
The website shows Server linked and online within a few seconds, followed by live players.

What happens afterwards

The plugin polls the website every five seconds while idle. While someone is using the console, or work is waiting, the website asks for one-second polling so actions land in about a second.
Every website action is queued, delivered to the plugin at most once, checked again by the plugin against its own rules and permissions, and written to plugins/ForgeGuard/cases/staff-audit.jsonl with the website member's e-mail before anything changes.
A request expires if the plugin does not run it within 30 seconds. The console then says the outcome is uncertain and never retries a write by itself.
Invite your staff from Members. Their website role (owner, admin, moderator or viewer) applies to this server only and never grants Minecraft permissions.

Pending requests and outages

If the approval expires, generate a new code and claim again.
After about 20 seconds without a heartbeat the website shows the server as offline and refuses live actions. The link is kept; it resumes when the server returns.
Stale status (no fresh snapshot) is refused rather than shown as current.

Hosting usage and limits

Idle polling is about 17,280 requests per server per day at five seconds. During active use it rises to one per second. Status uploads are capped at 256 KiB and at most one every two seconds, command results at 2 MiB, and each workspace has at most four pending and eight retained operations.

Disconnect or replace a server

On the website: Server setup → Unlink server (owners). Pending operations are discarded. The plugin learns on its next poll and removes its credential.
In Minecraft: Link web console → Unlink / cancel pairing, or /fg link unlink confirm. This works even if the website is unreachable.
Deleting the workspace also revokes the link. The plugin, its cases and its in-game tools keep running in every case.

Credentials and local testing

The device credential is 256 random bits, generated by the plugin and stored only in plugins/ForgeGuard/link-credentials.json (owner-only file permissions). The website stores only its hash and pins it to one site origin and one workspace. Keep that file out of public backups.

For local development, set link.allow-loopback-http: true and use http://127.0.0.1:<port>; the development website needs FORGEGUARD_ALLOW_LOCAL_HTTP=true. site/scripts/simulate-server.mjs stands in for a Minecraft server when you only need to exercise the website.