Home/Docs/Install

How to Install BlackGuard on Your FiveM Server

BlackGuard is a server-side anti-cheat for FiveM. It installs as standard server-side resources, validates your license against our cloud, and starts detecting cheats in real time. No client mods, no kernel driver, and nothing for your players to install. Most servers are fully protected in under five minutes.

New to this? You don't need to be technical. This is a copy-paste install: download three folders, drop them in, paste four lines, restart. The pictures below show exactly where everything goes.

Before you start

You'll need

✓A FiveM server (FXServer) you control.
✓Your BlackGuard license key: format BKGD-XXXXXXXX-2026, in your dashboard under Licenses.

You won't need

✕No MySQL or database.
✕No oxmysql, no ox_lib. Zero hard dependencies.
✕No client-side files, no kernel access, no false-kick tuning period.

Dashboard → Licenses. Your key lives here. Keep this tab open.

The resource only needs outbound HTTPS to blackguardac.com. (ox_lib/oxmysql appear only inside Config.AllowedResources, a known-safe allowlist, not a dependency.)

Folder permissions

Before you install, know that the resources folder needs to be writable by the game server process. The updater installs new versions into the folder your blackguard resource lives in, so it has to be able to write there.

Most hosts allow this by default. If you uploaded the files through a web file manager, check the folder's owner and permissions. Some host panels have a permissions tool that can remove that access again, so it is worth re-checking any time auto-updates stop. Step-by-step check below. Some shared hosts do not allow it at all, and there is no way around it from our side. BlackGuard still runs and still blocks cheaters. Updates are the only thing that stops. You can update by hand in about two minutes. The panel shows you the three steps.

Install in 4 steps

Download · from your dashboard

On the Download page, grab all three files:

›blackguard, the core anti-cheat resource (required).
›blackguard_watchdog, anti-tamper companion (required: an attacker would have to stop multiple resources to disable protection).
›blackguard_updater, safe auto-updater (required: keeps your resources current automatically; without it running your server never receives sensor updates).

Place the resources

Unzip all three folders into your server's resources/ directory (e.g. resources/[blackguard]/). That's the whole step. Just drop them in.

Drop all three folders straight into resources/, not inside another folder.

Installing on a remote host? Upload the zip and extract it on the server (use binary mode over FTP). Don't extract locally and upload loose files.

Configure `server.cfg`

Open your server.cfg and add this block. The key line goes before the ensure lines:

set bg_license_key is the primary method. It survives update zips. (Fallback: set Config.LicenseKey in blackguard/shared/config.lua; the convar wins if both are present.)

Start

Restart your server, or run ensure blackguard from the live console. That's it. You're protected.

Confirm it's working

On a clean boot you'll see these lines in your console:

Your server also shows Online in the dashboard within a minute or two (heartbeat).

If validation fails you'll see [BlackGuard] VALIDATION FAILED: <reason>, detection disabled. instead. See Common setup issues below.

Checking auto-updates

The updater checks its own folder every time the server starts, so the updater block above ends with one of these two lines.

If it can write to the folder:

server console

[BlackGuard Updater] write-probe OK (3 dirs)

If it cannot:

server console

[BlackGuard Updater] write-probe FAILED for blackguard — auto-updates WILL NOT APPLY on this host until fixed; see RECOVERY.md troubleshooting

Anything other than a clear pass means your protection will keep running but will not receive new versions. Make the resources folder writable by the game server process, or ask your host to restore write permission for it, then restart the server so the check runs again.

If your host will not allow it, you can update by hand instead: download the current version, upload the blackguard folder over the old one (keep your config file), and restart the server. The panel shows you the three steps and the download when your server cannot update itself.

To force a version check without waiting for the next scheduled poll, type bg_update_check in your server console. Running it also re-arms the folder check after you have fixed permissions, so the very next check can install what it missed.

Optional: Vision add-on (aimbot / ESP detection)

Vision takes secure screenshots and analyzes the rendered game image for visual cheat indicators: aim overlays, ESP, and wallhack visuals. It's two resources: fivem-bg-vision (needs screenshot-basic) + screenshot-basic.

Shadow-only and still being validated. Vision verdicts are recorded for review and never kick or ban on their own. Leave it disabled in production unless you're coordinating with BlackGuard.

server.cfg · Vision add-onCopy

# ── BlackGuard Vision (optional add-on) ──
set bg_license_key "BKGD-XXXXXXXX-2026"   # same key as core
set bg_api_url "https://blackguardac.com"
ensure screenshot-basic
ensure fivem-bg-vision

Clean-boot line: [bg_vision] Ready. Waiting for capture requests.

Scope (honest)

•Vision targets visual cheat overlays. Cheats that don't render anything on-screen may not be caught by Vision alone.

Privacy

•Capture & image use are disclosed in our Terms of Service; images are stored securely and auto-deleted after 14 days. Make sure your players know your server's ToS.

Framework compatibility

BlackGuard's core detection is framework-agnostic. It runs on ESX, QBCore, QBox, vRP, and standalone FiveM servers. Economy / money-exploit detection currently supports ESX and QBCore only (the two with money event hooks).

What BlackGuard detects

Cheat type	How it's handled
Speed hacks	Auto-ban
Teleport	Auto-ban
Impossible weapon-damage (server-verified)	Auto-ban
Resource injection (unknown resources)	Flagged for review
Economy / money exploits (ESX & QBCore)	Flagged for review
Aimbot / ESP	Optional Vision add-on
No-clip · super-jump · god-mode	Roadmap: not yet detected

Detection rules update automatically on our backend. You don't patch the resource when we improve a detection. Your installed resource is a sensor.

Common setup issues

?"Validation failed: bound to a different server."

Your key binds to the first server that validates it (by IP:port). Move it in Licenses → Reset Server Binding (up to 3 resets per 24h), then restart.

?Server never shows Online.

Confirm the console shows License validated. Detection active, and make sure outbound HTTPS (port 443) to blackguardac.com isn't firewalled (only outbound access is needed).

?Logs say watchdog_present:false.

You started blackguard without blackguard_watchdog. Add ensure blackguard_watchdog and restart.

?A trusted admin got banned for teleporting.

There's no staff-whitelist yet, so a large instant /tp can read as a teleport cheat. Clear it with one-click Revoke on the Bans page. (Staff-whitelist is on the roadmap.)

?Resource is corrupt after upload.

Files were transferred in text mode over FTP. Re-upload in binary mode, or upload the zip and extract on the server.

Keeping BlackGuard updated

•Detection rules update automatically, server-side. You don't patch the resource when we improve or add a detection. Your installed resource is a sensor.
•Resource updates apply automatically too. The blackguard_updater resource keeps the sensor current for you (verify → backup → swap → restart, with automatic rollback if anything fails). There's nothing to download or replace by hand. Keep blackguard_updater running. Without it your sensor never updates and drifts out of date.
•Because your key lives in the bg_license_key convar (not a file the update overwrites), your configuration survives updates. Nothing to re-enter.

Frequently asked questions

?How do I install an anti-cheat on a FiveM server?

With BlackGuard: download the blackguard, blackguard_watchdog, and blackguard_updater resources, drop all three folders into your resources/ directory, set bg_license_key in server.cfg before the ensure lines, and restart. Most servers are protected in under five minutes.

?How long does BlackGuard take to install?

Most servers are fully protected in under five minutes. There's no tuning period.

?How do I update BlackGuard?

Updates are automatic. Detection rules update server-side, and the blackguard_updater resource keeps the sensor files current for you. There's nothing to download or replace by hand. Keep blackguard_updater running; your key lives in the bg_license_key convar, so your config survives every update.

?Can I install BlackGuard on any FiveM host or VPS?

Yes. Any FiveM host or VPS you control that allows outbound HTTPS to blackguardac.com. The resource only needs outbound access.