<!-- fivemad.com, Markdown source of https://fivemad.com/docs/frameworks/qbox -->
> Source: https://fivemad.com/docs/frameworks/qbox
> Section: Frameworks
> Tags: qbox, qbx_core, framework, ox_inventory, ox_lib, jobs, items, roleplay
> Last updated: 2026-09-22
> Site map for assistants: https://fivemad.com/llms.txt

# Qbox quick start

Install Qbox with the txAdmin recipe, understand qbx_core and the ox stack, make yourself admin, add a job and an ox_inventory item, write a small Qbox script, avoid pitfalls.

Qbox began as a fork of QBCore and is now its own framework, built on the Overextended stack (ox_lib, ox_inventory, ox_target) with a compatibility bridge so many QBCore resources still run. Official docs: [docs.qbox.re](https://docs.qbox.re).

[Installing FiveM with QBox (BadCode.Codes)](https://www.youtube.com/watch?v=whEnm6baAnI) (YouTube video)

## 1. Requirements

From the Qbox installation docs:

- **MariaDB 10.9.0 or newer** (a current LTS is recommended). **MySQL is not supported, and XAMPP is not supported.** See [Database setup](/docs/server-setup/database).
- An up to date recommended artifact and a license key.
- txAdmin, which Qbox "highly recommends" for installing.

## 2. Install with txAdmin

1. Start FXServer, link your Cfx.re account.
2. **Popular Recipes > Qbox**.
3. License key, database connection (leave the name empty), **Run Recipe**.
4. **Save & Run Server**.

What the recipe installs is in [Popular recipes](/docs/txadmin/popular-recipes#qbox). Its config is split into `server.cfg`, `permissions.cfg`, `ox.cfg`, `voice.cfg` and `misc.cfg`, and it sets game build `3258`.

## 3. The structure

```text
resources/
├─ [cfx-default]/
├─ [ox]/             ox_lib, oxmysql, ox_target, ox_inventory, ox_doorlock, ox_fuel
├─ [qbx]/
│  ├─ qbx_core/      the framework
│  │  ├─ shared/     jobs.lua, gangs.lua, vehicles.lua, weapons.lua, locations.lua...
│  │  ├─ config/
│  │  └─ modules/    lib.lua, playerdata.lua (importable helpers)
│  ├─ qbx_garages/ ...
├─ [standalone]/     illenium-appearance, Renewed-Banking, scully_emotemenu...
├─ [voice]/          pma-voice, mm_radio
├─ [npwd]/           phone
└─ [assets]/         maps
```

Useful `server.cfg` convars from the recipe:

| Convar | Default in recipe | Meaning |
| --- | --- | --- |
| `qbx:enableBridge` | `"true"` | Enables the qb-core bridge so QBCore resources work. |
| `qbx:enableQueue` | `"true"` | qbx_core's built in join queue. |
| `qbx:max_jobs_per_player` | `1` | Multi job support if you raise it. |
| `qbx:enableVehiclePersistence` | `"false"` | Respawn deleted player vehicles. |
| `qbx:discordLink` | `"discord.gg/qbox"` | Change to your Discord. |

## 4. Make yourself admin

Qbox uses FiveM's ACE groups. The deployer already added **your** identifiers through `{{addPrincipalsMaster}}`, and `permissions.cfg` defines the groups. To add another admin:

```cfg title="permissions.cfg"
add_principal identifier.fivem:123456 group.admin
```

Restart, then open the admin menu (qbx_adminmenu) in game. qbx_core also has commands like `/setjob`, `/givemoney`, `/car`, `/dv` and `/tp`, and ox_inventory adds `/giveitem`.

## 5. Add a job

Jobs are in `qbx_core/shared/jobs.lua`. Job names must be lowercase, and grades use **number** keys:

```lua title="qbx_core/shared/jobs.lua"
return {
    -- ...existing jobs...
    ['burgershot'] = {
        label = 'Burger Shot',
        defaultDuty = true,
        offDutyPay = false,
        grades = {
            [0] = { name = 'Trainee', payment = 50 },
            [1] = { name = 'Cook', payment = 75 },
            [2] = { name = 'Manager', isboss = true, bankAuth = true, payment = 120 },
        },
    },
}
```

`isboss` gives access to the management menu, `bankAuth` to the society account. Police style jobs add `type = 'leo'`. Restart the server, then `/setjob [id] burgershot 2`.

> [!NOTE]
> The recipe sets `qbx:cleanPlayerGroups "true"`: on start, players' jobs and gangs that no longer exist in the config files are removed from the database. Don't delete a job from `jobs.lua` by accident.

## 6. Add an item (ox_inventory)

Qbox uses **ox_inventory**, so items are defined in `ox_inventory/data/items.lua`:

```lua title="ox_inventory/data/items.lua"
['burger'] = {
    label = 'Burger',
    weight = 220,
    stack = true,
    close = true,
    description = 'A juicy Burger Shot burger',
    client = {
        status = { hunger = 200000 },
        anim = 'eating',
        prop = 'burger',
        usetime = 2500,
    },
},
```

The `client` block alone makes it usable: ox_inventory plays the animation and prop, and the `status` field feeds hunger to the status system. Put `burger.png` in `ox_inventory/web/images/` (the [Inventory Icons](/tools/inventory-icons) tool makes transparent icons and `items.lua` entries). Test with `/giveitem [id] burger 1`.

For server logic on use, point the item at an export of your resource:

```lua title="ox_inventory/data/items.lua"
['lockpick'] = {
    label = 'Lockpick',
    weight = 160,
    server = { export = 'my_crime.lockpick' },
},
```

```lua title="my_crime/server.lua"
exports('lockpick', function(event, item, inventory, slot, data)
    if event == 'usingItem' then
        -- return false to cancel the use
        return true
    end
end)
```

Check the [ox_inventory docs](https://overextended.dev/ox_inventory) for the full item options (degrade, consume, buttons, weapons).

## 7. A small Qbox script

```lua title="my_paycheck/fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

shared_scripts {
    '@ox_lib/init.lua',
    '@qbx_core/modules/lib.lua',
}
server_script 'server.lua'

dependencies { 'ox_lib', 'qbx_core' }
```

```lua title="my_paycheck/server.lua"
local lastClaim = {}

lib.addCommand('paycheck', { help = 'Claim a bonus paycheck (once per hour)' }, function(source)
    local player = exports.qbx_core:GetPlayer(source)
    if not player then return end

    local cid = player.PlayerData.citizenid
    if lastClaim[cid] and os.time() - lastClaim[cid] < 3600 then
        exports.qbx_core:Notify(source, 'You already claimed it this hour', 'error')
        return
    end

    local job = player.PlayerData.job
    local amount = 100 + (job.grade.level * 50)
    exports.qbx_core:AddMoney(source, 'bank', amount, 'paycheck-bonus')
    lastClaim[cid] = os.time()
    exports.qbx_core:Notify(source, ('Paid $%d for %s'):format(amount, job.label), 'success')
end)
```

Key qbx_core server exports (from the [Qbox docs](https://docs.qbox.re)): `GetPlayer(source)`, `AddMoney(identifier, moneyType, amount, reason)`, `RemoveMoney(...)`, `SetJob(identifier, jobName, grade)`, `CreateUseableItem(item, cb)`, `Notify(source, text, type, duration)`, `GetPlayersData()`, `HasPrimaryGroup(source, filter)`. `identifier` can be a server ID or a citizen ID.

## Common pitfalls

- **MySQL or XAMPP**: not supported. Use MariaDB.
- **Mixing inventories**: Qbox is built around ox_inventory. Don't install qb-inventory next to it.
- **QBCore scripts**: most work through the bridge, but scripts that edit qb-core internals or use removed QBCore functions need changes. Check the Qbox docs' converting section.
- **Downloading ox resources from source**: use release zips.
- **Editing `jobs.lua` without a restart**: shared data is loaded on start.
- **Deleting jobs** with `qbx:cleanPlayerGroups` on: players lose that job from the database.

## Next steps

- Read the Qbox docs for each `qbx_*` resource's config.
- The [video archive](/docs/videos) has a Qbox series (jobs, boss menu, items) in the frameworks course.