Qbox Installation

The Qbox team recommends the txAdmin recipe strongly enough that the manual path is effectively unsupported. Use the recipe unless you have a specific reason not to.

Prerequisites

⚠️

Qbox targets MariaDB, not MySQL, and never XAMPP. The minimum is MariaDB 10.9.0; MariaDB 12.3 LTS is the recommended choice for new installs and is supported until June 2029.

The floor is not arbitrary. qbx_core uses:

Feature	Used for	Minimum
`JSON_VALUE()`	Phone, account and metadata lookups	10.6.1
`ADD COLUMN IF NOT EXISTS`	Player table migrations	10.0.2
`CREATE INDEX IF NOT EXISTS`	Identifier indexes on resource start	10.9.0

Cfx.re account created and a server registration key created in the Cfx.re Portal (portal.cfx.re/servers/registration-keys)
FXServer artifacts downloaded and extracted to a permanent path
MariaDB 10.9.0 or newer installed (12.3 LTS recommended)
Database and dedicated database user created
Confirmed you are not using XAMPP or MySQL

Install via txAdmin recipe

Download the artifacts

Download the Recommended Windows artifact (server.7z) from the official Server Download page and extract it into a folder named server.

Start FXServer

Run FXServer.exe. txAdmin opens its setup wizard in a browser tab.

Link your Cfx.re account

Choose the recipe

Select Popular Recipes, then QBox Framework.

Enter database credentials

The deployer downloads server.cfg, ox.cfg, permissions.cfg, voice.cfg and misc.cfg, then creates the schema.

Start the server

Once the recipe finishes, start the server from the txAdmin dashboard.

Official installation guide →

Manual installation

If you are not using the recipe, you must supply the config files yourself — they are not in the qbx_core repository.

Get the config files

Take server.cfg, ox.cfg, permissions.cfg, voice.cfg and misc.cfg from the Qbox txAdminRecipe repository.

Install the dependencies

Download releases of oxmysql, ox_lib, ox_inventory and ox_target.

Install qbx_core

git clone https://github.com/Qbox-project/qbx_core.git

Import the SQL

Run qbx_core.sql against your database, then confirm players.citizenid uses the utf8mb4_unicode_ci collation.

Start the resources

ensure oxmysql
ensure ox_lib
ensure qbx_core
ensure ox_inventory
ensure ox_target

Configuration

Qbox configures itself through convars rather than Lua config files:


setr qbx:enablequeue true
setr qbx:max_jobs_per_player 1
setr qbx:max_gangs_per_player 1

Multicharacter is toggled with useExternalCharacters in qbx_core/config/client.lua; queue behaviour lives in qbx_core/config/queue.lua.

Convar reference →

Validation

Console reaches "Started resource qbx_core" with no errors
No CREATE INDEX or JSON_VALUE errors on startup (these mean MariaDB is too old)
Database contains players and player_groups tables
You can connect, create a character and spawn
ox_inventory opens and items persist across a reconnect

Rollback

Stop FXServer
Drop and recreate the database, then restore your last dump
Restore the previous resources folder and all five .cfg files
Confirm players can connect before trying again

See Backups.