Installation

This guide takes you from a redeemed license to a protected server. You need a license first, see Buying and redeeming, and a server that meets the requirements.

Download the resource#

The resource is downloaded from the dashboard, not from a public link, because the ZIP is generated for your license and contains your license key.

1. Open the dashboard and select your server.
2. Click Manage resource, then Download resource, and pick the latest version if the dialog asks. If this is your only server and it has never connected, the dashboard opens the Setup Wizard for you instead, with a Download Resource button.
3. Save the ZIP. Its name contains the version, for example AstroShield-1.0.0.zip.

Extract it into your resources folder#

The ZIP already contains a top-level AstroShield folder. Extract it into resources so the path is:

resources/
└── AstroShield/
    ├── fxmanifest.lua
    ├── client-obfuscated.lua
    ├── server-obfuscated.lua
    ├── shared-obfuscated.lua
    ├── websocket.js
    ├── recorder.js
    ├── index.html
    ├── ui.js
    ├── ui.css
    ├── .version
    └── .key

You can place the folder in a category folder such as resources/[security]/AstroShield. The folder name itself must stay AstroShield.

Add the resource to server.cfg#

Add these three lines to your server.cfg, above the rest of your resources:

start AstroShield
add_ace resource.AstroShield command allow
add_unsafe_child_process_permission AstroShield

If the permissions are missing, the console prints Missing permissions! Add to server.cfg: followed by the lines to add, and AstroShield stays offline until you add them and restart.

Start the server#

Start or restart your server. In the console you should see AstroShield's banner:

                         https://astroshield.dev
                         Project: My Roleplay Server
                         License: 6ad3f1c20b9e47a51c8d3f62
                         Version: 1.0.0
                         Expires: 2026-12-01
                         Status:  License active

The Status line tells you where you stand. License active or Lifetime license means everything is fine. Anything else is explained in License statuses.

The first start changes your other resources#

Straight after the banner, AstroShield runs astroinstall. It adds its shared guard to every other resource by inserting one line at the top of that resource's manifest. You see one line per resource and a summary:

[AstroShield] Starting installation...
[AstroShield] Installed to esx_policejob
[AstroShield] Installed to qb-inventory
[AstroShield] Results: 87 installed, 0 already installed, 0 failed
[AstroShield] Restart the server (or the changed resources) to load the protection.

The resources only load the guard the next time they start, so restart the server once more after the first start. After that, astroinstall runs on every start and only touches resources that are new.

Check that it works#

• The console banner shows your project name and a valid status.
• In the dashboard your server is Online and the player list fills up. See Dashboard overview.
• Typing astroshield status in the server console prints the connection, license and module state. See Console commands.

What astroinstall changes#

For each resource except AstroShield itself, _cfx_internal, monitor (txAdmin) and webadmin, AstroShield adds this line at the top of fxmanifest.lua (or __resource.lua):

shared_script '@AstroShield/shared-obfuscated.lua'

• Only manifests are changed. Your scripts are never edited.
• It is safe to run again. Resources that already have the line are skipped.
• It needs the two permission lines above. Without them the console says Automatic astroinstall skipped: missing permissions.
• Failed: resource_name means that manifest could not be read or written, usually a file permission problem. Fix the permission, or add the line by hand.
• If you deploy your resources from a repository or a build step that overwrites manifests, run astroinstall in the console after the deploy.
• To remove the line from every resource, run astrouninstall. See Uninstalling.

What the guard does inside your resources is explained in Shared guard.

Windows and Linux notes#

AstroShield writes files through a short-lived child process, because FiveM does not let resources create files themselves. On Windows it uses PowerShell, on Linux it uses mkdir and tee. Both must be available to the user the FiveM server runs as, and that user needs write access to the resources folder.

Next steps#