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-DEMO0000-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 used a web file manager, check who owns the folder and who can write to it. 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

If the check does not pass, your protection keeps running but gets no 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. Get the new files and drop the blackguard folder over the old one. Keep your config file and restart the server. The panel has the download and the steps when your server cannot update.

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.

Set what each check does

Every server runs the same checks, but you decide what each one does on your server. In your dashboard open Servers, pick your server, then Settings → Checks. A fresh install already runs the platform defaults, so this step is optional. Changes apply on the next event: no restart, nothing to redeploy.

The headline control is Mode, one click:

›Watch only: every check logs, nobody is removed.
›Balanced: the platform defaults, exactly what a fresh install already does.
›Custom: your own per-check settings.

Under the mode, one sentence states what the server will do, for example "3 checks can remove players · 2 set to log · sensitivity normal". Fine-tune each check (collapsed by default) opens three groups: Enforcement (the checks that can remove a player), Griefing and Monitoring (review-only checks you can switch on or off).

Enforcement checks and their actions

Check	Off	Log	Kick	Ban
Teleport	Not checked	Review row, nobody removed	Removed, no ban written	Removed and banned · default
Impossible speed	Not checked	Review row, nobody removed	Removed, no ban written	Removed and banned · default
Impossible damage	Not checked	Review row, nobody removed	Removed, no ban written	Removed and banned · default

Each enforcement check also has a sensitivity: Low, Normal or High. Low widens the tolerance before a kick, so borderline cases (modded vehicles, long admin jumps) trip less. High trips sooner, but it applies only while the action is Log or Kick and never lowers a ban line: turning sensitivity up can never make a ban easier to earn.

Griefing checks (Mass entity spawn: Inherit, Off, Log or Kick · Explosion burst: Inherit, Off or Log) follow the platform setting until you change them. Monitoring checks are review-only: Log records them for you, Off stops recording them. None of these can ban.

New server? Start in Watch only. Run it for a day or two. Every trip lands in your review queue as a log row and nobody is removed, so you see exactly what trips on your server (modded vehicles, admin teleports, custom weapons) before you switch kicks or bans on. Then pick Balanced, or Custom for any check you want to keep softer.

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.

Flags for review, never an automatic ban. Vision raises aimbot, ESP, and wallhack indicators for your team to review, and it never kicks or bans anyone on its own.

server.cfg · Vision add-onCopy

# ── BlackGuard Vision (optional add-on) ──
set bg_license_key "BKGD-DEMO0000-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 kept for up to 30 days, then deleted. 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 (visual overlays)	Optional Vision add-on (Pro tier and up) · flags for review
No-clip / god-mode	Flagged for review · never auto-banned
Super-jump	Not detected, we don't claim what we can't back

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

The auto-ban rows above are the Balanced defaults. You can set any of them to off, log or kick per server under Set what each check does.

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.

?Can I control what each check does?

Yes, per server. In your dashboard open Servers → your server → Settings → Checks. Pick a mode in one click: Watch only (everything is logged, nobody is removed), Balanced (the platform defaults) or Custom. Under Fine-tune, each enforcement check can be set to off, log, kick or ban with a sensitivity of low, normal or high. Changes apply on the next event, with no restart. See Set what each check does.