QBCore has been the default recommendation for new roleplay servers for years, but a lot of 2026 setup guides now point somewhere else first: Qbox. If you have not looked closely, it is easy to assume that is just a renamed QBCore, and that assumption causes real setup mistakes.

Short answer: Qbox is a separate framework built around qbx_core, using ox_lib, oxmysql, and ox_inventory instead of standalone libraries, with a bridge layer that keeps most existing QBCore resources working. Setting it up correctly means installing that dependency stack in the right order, enabling OneSync, meeting the minimum server build qbx_core itself declares, and importing its SQL schema before first boot.

What Qbox actually is

Qbox is developed under the Qbox-project organization on GitHub. Its own README describes qbx_core as "a framework created on September 27, 2022, as a successor to qb-core," built to continue QBCore's foundation while adopting the overextended ox libraries that also power ox_lib and ox_inventory. The project ships a bridge layer described in the same README as providing "backwards compatibility with most QB resources with 0 effort required," which is the main reason server owners can move to it without rewriting an existing script library from scratch. Under the hood, qbx_core's own resource manifest declares provide 'qb-core', which is what makes that compatibility work at a technical level: any script that lists qb-core as a dependency resolves against qbx_core automatically, without the script itself needing to be edited or renamed.

Under the hood it still includes familiar QBCore concepts: built-in multicharacter support, multi-job and multi-gang handling, a queue system for full servers, and persistent player vehicles, all exposed through an export-based API rather than a single global core object.

qbx_core also exposes three optional modules for anyone building custom resources on top of it: Hooks, which lets other resources extend qbx_core's behavior in an ox-style pattern; Logger, which routes log output either to Discord or through ox_lib's own logger; and Lib, a set of common helpers for tables, strings, math, native audio, vehicles, and drawing text. None of the three are required to run a server, but they matter if you or a developer plan to write anything custom against Qbox rather than only installing pre-built scripts.

Prerequisites before you install anything

  • MariaDB, not plain MySQL.Qbox's setup documentation specifies MariaDB 10.9.0 as the practical minimum, with the 12.3 LTS release recommended, and explicitly states that XAMPP is not supported.
  • A current FXServer artifact.qbx_core's own fxmanifest.lua lists /server:10731 as a dependency, meaning that build number is the minimum server version it expects to run against. Use the official txAdmin setup guide if you have not stood up a server yet.
  • OneSync enabled. It is listed as a direct dependency in the same manifest, alongside ox_lib and oxmysql.
  • A free license key from Cfx.re Keymaster.

Two ways to install: recipe or manual

The recipe path

Qbox's own setup documentation is direct about which path it recommends: it says plainly that it highly recommends using txAdmin to install your FiveM server rather than assembling one resource at a time. During the setup wizard, download the latest FXServer artifacts, extract them, launch FXServer.exe, and once txAdmin is running, choose Popular Recipes and select the QBox Framework recipe. It installs qbx_core, ox_lib, oxmysql, and ox_inventory together and runs the required SQL automatically, which removes most of the manual sequencing risk described below.

The manual path

If you are building resource-by-resource, clone or download each dependency from its official repository: oxmysql, ox_lib, ox_inventory, and qbx_core itself. This gives you more control over versions but puts the load order entirely on you.

The dependency stack, in the order it actually loads

qbx_core's fxmanifest.lua declares its dependencies as /server:10731, /onesync, ox_lib, and oxmysql, and its server scripts import @oxmysql/lib/MySQL.lua and @ox_lib/init.lua directly. ox_inventory adds one more link to the chain, since it needs both oxmysql and ox_lib plus a framework resource already running before it starts. In practice, your server.cfg should ensure resources in this order:

set onesync on

ensure oxmysql
ensure ox_lib
ensure qbx_core
ensure ox_inventory

Telling ox_inventory it is running on Qbox

ox_inventory does not detect your framework automatically; it reads a convar that defaults to ESX if you never set it. On a Qbox server, set it explicitly in server.cfg:

setr inventory:framework "qbx"

Note the value is qbx, matching the bridge folder ox_inventory loads internally, not qbox or qb. Getting this string wrong is a common, easy-to-miss mistake, since the server boots fine either way and only the inventory integration silently fails to bridge correctly. ox_inventory also checks minimum versions of its two dependencies on startup and refuses to load if either is too old, so keep oxmysql and ox_lib current rather than pinned to whatever version you installed first. If you are also running ox_target for interaction prompts, start it before ox_inventory; ox_inventory checks for it at boot and logs a warning if it is not already running.

Database setup

qbx_core ships its own schema file, qbx_core.sql, inside the resource. Import it into the MariaDB database your connection string points to before first boot. If you are migrating an existing QBCore database rather than starting fresh, Qbox's own migration documentation lists three required schema changes beyond running that file: add a last_logged_out column to the players table, change the collation of players.citizenid to utf8mb4_unicode_ci, and create a new player_groupstable to support Qbox's multijob system.

Migrating existing QBCore scripts

This is the part owners considering a switch usually worry about most, and the practical answer is that it is less disruptive than rewriting a framework migration usually implies. Qbox's own documentation describes roughly 99 percent compatibility with existing QB scripts through the bridge layer, so most jobs, garages, and shop scripts keep working without edits.

The changes that do require attention: job and gang grades switch from quoted string values to plain numbers, which means updating qbx_core/shared/jobs.lua and qbx_core/shared/gangs.luato match. In the current qbx_core repository, a job definition's grades look like this:

['police'] = {
    label = 'LSPD',
    type = 'leo',
    grades = {
        [0] = { name = 'Recruit', payment = 50 },
        [1] = { name = 'Officer', payment = 75 },
    },
}

Notice the grade keys are plain numbers in square brackets, not quoted strings like ['0']. A job config copied directly from a QBCore server with quoted grade keys will not error loudly; it will simply fail to match ranks correctly, which is exactly the kind of silent bug that is expensive to track down after launch.

The global core object is also gone. Code that read from it directly needs to move to export calls, for example replacing a direct QBCore.Shared.Jobs reference with exports.qbx_core:GetJobs(). Neither change is difficult on its own, but skipping them is the most common reason a migrated script loads without errors and then behaves incorrectly at runtime.

The bridge layer solves compatibility. It does not solve the handful of breaking changes Qbox lists explicitly, and those are exactly the ones that get skipped during a rushed migration.

First boot checklist

Start the server and confirm oxmysql reports a successful database connection before anything else. qbx_core should load without dependency warnings referencing ox_lib or oxmysql. Connect with a client and confirm the built-in multicharacter flow presents a character screen, then create a character and restart the server to confirm the data actually persists in the database you just imported.

Work through this before opening the server to real players:

  • Create and delete a character to confirm both the creation and cleanup paths hit the database correctly.
  • Assign yourself a job and a gang and confirm the correct grade name and rank show up after reconnecting, not just immediately after the command.
  • Open ox_inventory as a player and confirm it loads the framework's item list rather than showing an empty or default inventory.
  • Restart the server with no one connected to confirm a cold boot produces no dependency errors, since a warm restart can mask a load-order problem a cold one will not.

Where a working install stops being enough

A clean Qbox boot tells you the framework is healthy. It does not tell you whether the two dozen scripts you plan to run on top of it were actually built or verified against Qbox's bridge layer rather than against raw QBCore. That gap is where scoped build and compatibility work earns its keep, particularly for owners migrating an active community rather than starting from zero.

If you have not committed to Qbox yet, our framework fit comparison lays out how it stacks up against QBCore and ESX for different server types before you invest setup time in any of them.

The bottom line

Qbox is not QBCore with a new name. It is a distinct framework built on the ox ecosystem, and treating it that way, respecting its declared dependency order, its MariaDB requirement, and its documented migration changes, is what separates a stable launch from a server that boots fine and then breaks the first time a real player touches a job or gang system.