Qbox FiveM server: setup, resources and load order

The quickest working Qbox server is the official txAdmin recipe: start FXServer, open txAdmin, pick Popular Recipes and then QBox Framework, give it a database, and let it download around sixty resources and import the SQL. Underneath, the whole thing rests on five resources - qbx_core, ox_lib, oxmysql, ox_inventory and ox_target - and on three requirements people miss: OneSync switched on, a recent FXServer build, and a MariaDB database rather than MySQL. Everything else in this post is how those pieces fit together, where to get the rest of the Qbox resources, the convars that change how the core behaves, and what the console is telling you when it does not start.

If you have not yet decided between frameworks, ESX vs QBCore vs Qbox is the comparison. This post assumes the decision is made.

What Qbox needs before you install anything#

Qbox is a fork of QBCore rebuilt on the Overextended (ox_*) resources. It is stricter about its environment than QBCore ever was, and most failed first starts are an environment problem, not a Qbox problem.

The server build. The current qbx_core manifest carries a dependency of the form /server:10731, which means FXServer refuses to start the resource on anything older. The number moves up as Qbox adopts newer natives, so read the manifest of the release you downloaded rather than trusting a number from a forum post, including this one. If you are behind, updating FiveM server artifacts covers how to move to a newer build without breaking everything else.

OneSync. Qbox does not run without it. Depending on your txAdmin version it is either a setting on txAdmin's FXServer settings page or a set onesync on line in server.cfg; the Qbox recipe's server.cfg does not write one, so check which applies to yours. The OneSync and player slots post explains what it actually changes and why every modern framework depends on it.

MariaDB, not MySQL. This is the one that surprises people. The Qbox installation guide is blunt: MariaDB 10.9.0 is the minimum, a current LTS release is recommended, MySQL is not supported, and XAMPP should never be used. oxmysql will happily connect to either engine, so a MySQL server will usually get you through the first start - the trouble comes later, in SQL that relies on MariaDB behaviour, in collation mismatches between tables, and in the fact that nobody in the Qbox support channels will help you debug it. If you are on a hosted database and do not know which engine it is, run SELECT VERSION(); in phpMyAdmin. A MariaDB server says so in the version string; a bare number such as 8.4.x is MySQL.

Installing with the txAdmin recipe#

The recipe is a YAML file that txAdmin runs top to bottom: it downloads repositories, unpacks them into folders, writes the config files and imports SQL. The Qbox one is maintained by the Qbox project and appears under Popular Recipes on a current txAdmin.

1. Start FXServer with an empty data folder. txAdmin opens and gives you a PIN to link your Cfx.re account.
2. Choose Popular Recipes, then QBox Framework.
3. Paste your Cfx.re licence key when asked. The key is yours, generated on the Cfx.re portal - see FiveM server and txAdmin for where it comes from.
4. Enter the database details. txAdmin builds a connection string from them and runs every SQL file in the recipe against that database.
5. Let it finish, review the generated server.cfg in the editor txAdmin shows you, and start the server.

The recipe downloads a lot. At the time of writing it lays out resources like this:

resources/  [ox]/          ox_lib, oxmysql, ox_target, ox_inventory, ox_doorlock, ox_fuel  [qbx]/         qbx_core, qbx_spawn, qbx_garages, qbx_police, qbx_ambulancejob...  [standalone]/  cfx defaults, illenium-appearance, Renewed-Banking, loadscreen...  [voice]/       pma-voice, mm_radio  [npwd]/        npwd (phone), qbx_npwd  [npwd-apps]/   phone apps  [assets]/      map assets

It also writes five config files to the server root: server.cfg, permissions.cfg, ox.cfg, voice.cfg and misc.cfg. Splitting them is deliberate - server.cfg stays readable, and the long list of ox_inventory and ox_target settings lives in ox.cfg.

The SQL it imports is several files, not one: a base qbox.sql, then qbx_core.sql, then the vehicle, vehicle shop, vehicle sales, weed, lap race and drug tables, and the phone's own import. That matters if you ever rebuild by hand, because skipping one leaves a resource that starts cleanly and then throws ER_NO_SUCH_TABLE the first time somebody uses it.

Treat the recipe as a starting point. It installs jobs, robberies and a phone you may not want, and every one of them is something to update and something that can break. A common and sensible move is to let the recipe build a server, play on it for an evening to see what Qbox looks like when it works, and then cut the [qbx] folder down to what your server is actually about.

The core resources and what each one does#

Five resources carry the framework. Everything else is optional; these are not.

`qbx_core` is the framework itself: players and characters, money, jobs and gangs (with built-in multijob), the connection queue, the character selection screen, and the compatibility bridge that answers to qb-core. Its configuration is under qbx_core/config/ (client.lua, server.lua, shared.lua), and its game data - jobs, gangs, vehicles, weapons - is in qbx_core/shared/. Unlike QBCore, Qbox has no core object. You call exports directly:

local player = exports.qbx_core:GetPlayer(source)if not player then return endplayer.Functions.AddMoney('bank', 500, 'weekly-wage')

`oxmysql` is the database bridge. It reads mysql_connection_string and gives every other resource its query functions. FiveM databases and oxmysql has the connection string, the import and the slow-query work, so it is not repeated here.

`ox_lib` is the shared library: callbacks, notifications, menus, progress bars, zones, locales. Almost every Qbox resource loads it with '@ox_lib/init.lua' in its manifest. Notifications in Qbox go through ox_lib, which is why swapping in your own notification resource means editing ox_lib rather than qbx_core.

`ox_inventory` replaces the slot inventory QBCore shipped. Items are defined in ox_inventory/data/items.lua, shops and stashes are data files beside it, and the item images live in ox_inventory/web/images. It must be told which framework it is running under, through setr inventory:framework "qbx" - the recipe's ox.cfg sets this, and a hand-built server that forgets it gets an inventory that cannot find any players.

`ox_target` is the third-eye interaction system: hold a key, look at a thing, get options. Most Qbox jobs register their interactions with it, so a server without it has police and mechanics who cannot do anything.

Around those five, the recipe adds the pieces a roleplay server assumes exist: qbx_spawn for spawn selection, qbx_vehicles and qbx_garages for owned cars, qbx_vehiclekeys, qbx_medical and qbx_ambulancejob, qbx_police, illenium-appearance for clothing, Renewed-Banking, and pma-voice for proximity voice.

Where to find Qbox resources#

Everything official lives in the Qbox-project organisation on GitHub, and every official resource is named with the qbx_ prefix. The documentation site at docs.qbox.re has a page per core resource with its exports, events and convars.

Three rules save most of the trouble:

• Download releases, not the green Code button. ox_lib and ox_inventory have web interfaces written in a frontend framework, and the source tree does not contain the built files. A release zip does. A server running ox_inventory from a source download prints a warning that the UI has not been built, and players open an inventory that is not there. The Qbox docs also recommend running only released versions of their own resources for stability.
• Version numbers below 1.0.0 mean beta. Qbox says so directly. They are usable, but expect breaking changes between minor versions.
• Archived repositories are finished, not abandoned. A few older Qbox resources were archived when their job moved elsewhere - usually into qbx_core or an ox_* resource. If a guide tells you to install a resource whose repository is archived, check what replaced it before installing it.

Third-party resources fall into three groups. Resources written for Qbox work as you would expect. Resources written for the Overextended stack (ox_* aware) usually work, since Qbox is built on it. Resources written for QBCore run through the bridge - covered in the next section - with real limits.

When you find a resource, read its fxmanifest.lua before you install it: the dependencies block tells you what it needs, lua54 'yes' tells you it is current, and anything calling os.execute or sending HTTP requests to an unknown domain is a reason to stop. Keeping a modded server clean is the longer argument for doing that every time.

Ensure order and how the recipe starts things#

Here is the start sequence the Qbox recipe writes, with its comments trimmed:

exec voice.cfgexec ox.cfgensure mapmanagerensure chatensure spawnmanagerensure baseeventsensure ox_libensure qbx_coreensure ox_targetensure [ox]ensure [qbx]ensure [standalone]ensure [voice]ensure [assets]ensure [npwd-apps]ensure qbx_npwdensure npwdexec permissions.cfgexec misc.cfg

Two things in it look wrong and are not.

First, oxmysql is never named before qbx_core. It does not need to be, because qbx_core declares oxmysql and ox_lib in its manifest's dependencies, and FXServer starts a resource's dependencies before the resource itself. The explicit ensure ox_lib is there for clarity; the dependency mechanism would have done it anyway. This is also why a missing oxmysql folder fails loudly at qbx_core rather than silently later.

Second, ensure [ox] runs after qbx_core even though ox_inventory is in that folder. That is correct: ox_inventory running under Qbox wants the core already up so it can read players and their items. An ensure of a bracketed folder starts every resource inside it, in no order you should rely on, so anything with a strict order is named on its own line before the folder.

The rules for your own additions follow from that. A resource that uses Qbox exports goes after qbx_core. A resource that uses ox_inventory items goes after [ox]. If you put your own resources in a folder such as [custom], add ensure [custom] at the end of the list, after [qbx]. And the exec ox.cfg line has to come before the ensure lines, because setr values are read when a resource starts - a convar set after its resource is running does nothing until the next restart. Every directive in the file is explained in FiveM server.cfg explained.

The qbx_core convars#

Qbox moved a lot of what used to be Lua config into convars, so the behaviour of the core is changed in server.cfg rather than by editing files that the next update overwrites. These are the documented ones, with their defaults:

A few deserve a sentence each.

Multijob. Raising qbx:max_jobs_per_player to 3 and setting qbx:setjob_replaces to false gives you multijob with no extra resource: /setjob adds a job instead of overwriting the current one, and the player switches between them. This is the single most common reason people used to install a separate multijob script on QBCore.

`cleanPlayerGroups`. On start, the core removes rows from player_groups that point to jobs or gangs no longer defined in qbx_core/shared/. That is what you want after deleting a job - and a nasty surprise if you renamed a job in jobs.lua and expected everyone to keep it. Rename by adding the new job, moving people across, then removing the old one.

Vehicle persistence. FiveM occasionally deletes entities it should not, and an owned car vanishing mid-drive is the result players notice. qbx:enableVehiclePersistence respawns it with its properties. The recipe writes it with setr rather than set, as it does qbx:enableBridge, because the client side reads them too. Keep the same verb when you change them.

`bucketLockdownMode`. relaxed and strict stop clients from creating networked entities in the default routing bucket, which is the main route for spawn-spamming cheats. strict breaks any resource that spawns entities from the client, so test it on a staging copy first.

Remember the set versus sets rule from every other FiveM guide: sets publishes the value to the server list. None of these values is secret, but the habit of writing set matters for the one line that is - mysql_connection_string.

QBCore resources on Qbox: the bridge#

With qbx:enableBridge on, qbx_core declares provide 'qb-core', so a resource that lists qb-core as a dependency is satisfied, and exports['qb-core']:GetCoreObject() returns an object that behaves like QBCore's. Most well-written QBCore resources run unchanged.

What does not survive the bridge:

• Direct table access. A resource that writes to QBCore's players columns itself, instead of using player functions, bypasses Qbox and may write to columns that are now structured differently.
• Inventory code. Anything that calls qb-inventory exports or expects QBCore's item format needs its inventory calls rewritten for ox_inventory.
• Non-public internals. Resources that read files out of qb-core/ directly, or rely on behaviour QBCore never documented, break in ways that are tedious to trace.
• Multijob scripts with their own tables. They conflict with the built-in multijob; the Qbox docs say they can work only if they go through qbx_core exports.

Items are the one place where the bridge goes both ways. An item added to qbx_core/shared/items.lua is passed through to ox_inventory automatically, which keeps bridged QBCore resources happy. But item behaviour that needs client or server exports - using an item, for example - still has to be written into ox_inventory/data/items.lua by hand. For a new item that only Qbox-aware resources use, define it in ox_inventory directly and skip items.lua altogether.

Admins and permissions#

The recipe's permissions.cfg holds the ACE setup. txAdmin writes your own identifier into it as the master admin during the install, as a line of the form add_principal identifier.fivem:1234567 group.admin. Qbox's admin commands - /setjob, /setgang and the rest - are restricted commands checked against ACE groups, so everyone who should use them needs a principal line. The file is read when server.cfg executes it, so after editing it, restart the server or run exec permissions.cfg in the live console.

Keep the admin list in permissions.cfg and nowhere else. A permission granted from inside a resource's Lua is invisible when you audit the file, and it is exactly what a backdoored resource does. Discord permissions and whitelists for FiveM covers tying these groups to Discord roles instead of typing identifiers.

Common startup errors and what they mean#

Read the console from the top, not the bottom. The first red line is usually the cause, and the fifty after it are resources failing because the first one did. Reading the console is the general method.

`qbx_core` refuses to start with an unsatisfied dependency on `/onesync` or `/server:`. OneSync is off, or the FXServer build is older than the manifest asks for. Turn OneSync on in txAdmin's settings, or update the artifacts. No amount of editing qbx_core fixes this.

"No such export GetCoreObject in resource qbx_core". A QBCore resource is asking qbx_core for the core object, which Qbox does not have. The fix is in the resource: it should call exports['qb-core']:GetCoreObject(), which the bridge answers. Also check the bridge is not switched off.

"This resource is still using the deprecated qbx_core utils". A warning, not an error. The named resource is an old release; download its latest version.

Players stuck on the loading screen. On a stock install this is nearly always the character selection never closing the loading screen, typically after replacing the built-in multicharacter. Either set loadscreen:externalShutdown to false in server.cfg or have your character resource call ShutdownLoadingScreen() and ShutdownLoadingScreenNui(). If you did not replace anything, look further up the console for a resource that failed to start - qbx_spawn or oxmysql failing produces the same symptom.

"Can't create table ... (Foreign Key Constraint is incorrectly formed)". A collation mismatch between the table being created and the one it references - common when SQL from different resources was written with different defaults, and more common still on MySQL. Qbox's fix is to end the CREATE TABLE statements with an explicit character set and collation, then drop and re-create the table:

CREATE TABLE IF NOT EXISTS example_table (  id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,  citizenid VARCHAR(50) NOT NULL) DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

"SCRIPT ERROR: failed to load model". A model did not load within the timeout, usually on a slow client. If the error comes from qbx_core, raise loadingModelsTimeout in qbx_core/config/client.lua.

Inventory opens empty or not at all. Either ox_inventory is a source download without its built UI, or inventory:framework is not set to qbx because ox.cfg was never executed. Check for exec ox.cfg above the ensure lines.

`ER_NO_SUCH_TABLE` from one feature. One of the recipe's SQL files was not imported. Find the resource's .sql file and import it through phpMyAdmin - the phpMyAdmin import guide covers large files - after reading its first lines for any DROP TABLE.

Running Qbox on a hosted server#

On RE:NODE, a FiveM server has txAdmin available, so the recipe flow above works as written: the server starts into txAdmin, you link your Cfx.re account and paste your own licence key. The plan includes a database slot created from the panel with a generated host, user and password, and an Open in phpMyAdmin button that signs you in with a one-use token. The panel does not name the engine behind that slot, so run SELECT VERSION(); before you commit to Qbox, and if it is not MariaDB, decide with your eyes open whether you can live with an unsupported database.

The file manager unpacks release zips in place, which is how you replace a resource with a newer release without a local copy of the server, and SFTP handles the bulk uploads such as a full [qbx] folder. Memory is the plan limit: the full recipe with its phone, map assets and every job is heavier than a cut-down list, so how much RAM a FiveM server needs is worth reading before choosing a tier. If the server reaches the limit it is stopped and restarted clean rather than swapping, so a server that keeps restarting under load is a sizing problem to look at with resmon and txAdmin's monitor, not a mystery.

Before updating any Qbox resource, take a backup and export the database. Qbox releases change schemas more readily than QBCore did, and a staging server running a copy of the database - see staging and production on one account - is where the update should meet your resource list first.

FAQ#

Is Qbox compatible with QBCore scripts?

Mostly. The bridge answers to qb-core and handles its documented exports and events. Scripts that touch QBCore's tables directly, use the old inventory, or rely on undocumented internals need changes. Test each one rather than assuming.

Do I have to use the txAdmin recipe?

No, but it is the fastest way to a known-good starting point. By hand, you need the five core resources from their releases, the SQL from qbx_core and each feature resource, ox.cfg or equivalent setr lines, OneSync on, and the ensure order shown above.

Can I remove resources the recipe installed?

Yes. Delete the folder and, if it was named on its own ensure line, remove that line. Check nothing else lists it in its manifest's dependencies first. Leave the core five alone, and be careful with anything in the character flow - spawn selection and clothing - since removing those shows up as players who cannot finish creating a character.

Where do I add a new job?

In qbx_core/shared/jobs.lua, as a table entry with its grades, followed by a restart. A job resource then gives it something to do. Players are assigned with /setjob, which adds or replaces depending on qbx:setjob_replaces.

Why does Qbox insist on MariaDB?

Its documentation names MariaDB 10.9 as the minimum and states MySQL is not supported, so its SQL and its support are written against MariaDB. A MySQL server often works in practice, but problems on it are yours to solve.

How many players can a Qbox server hold?

That depends on OneSync and your licence tier rather than on Qbox. The framework itself costs very little per tick; the resource list you build on it and the streamed assets decide the hardware.