# Installation

This page takes you from the downloaded zip to a running inventory.
If you already run ox_inventory, you replace it — players keep their items, stashes and vehicle inventories.

## Requirements

| Resource | Required | What it is used for |
| --- | --- | --- |
| FiveM server build 6116+ with OneSync | Yes | Same as ox_inventory |
| [ox_lib](https://github.com/overextended/ox_lib) 3.36.4+ | Yes | Callbacks, keybinds, notifications, locales |
| [oxmysql](https://github.com/overextended/oxmysql) 2.7.3+ | Yes | Inventories and the `koja_inv_*` tables |
| A framework | Yes | ESX, Qbox, ox_core or ND — chosen with the `inventory:framework` convar |
| [ox_target](https://github.com/overextended/ox_target) | No | Target zones for shops, stashes, crafting benches, dumpsters and trunks |
| illenium-appearance or [Koja Appearance](/new/appearance) | No | Real clothing thumbnails and saving the appearance after a clothing change |

:::hint{type="warning" title="Remove the original first"}
Do not run Koja Inventory next to another copy of ox_inventory.
It registers the same exports, events and callbacks under the same resource name.
:::

## Install

:::steps

### Put the resource in `resources`

Unpack the release zip. It contains one folder, `ox_inventory`, with the UI already built in `web/build`.

```text
resources/
└── [ox]/
    └── ox_inventory/
```

Keep the folder name `ox_inventory`. Other scripts call `exports.ox_inventory`, so a different name breaks them.

### Add it to `server.cfg`

Start it after its dependencies and your framework, and before the scripts that use it:

```cfg title="server.cfg"
ensure oxmysql
ensure ox_lib
ensure es_extended            # or qbx_core / ox_core / ND_Core
ensure ox_target              # optional, must start before ox_inventory
ensure illenium-appearance    # optional, clothing images
ensure ox_inventory

setr inventory:framework "esx"   # esx / qbx / ox / nd
setr inventory:slots 35          # 5 pockets + 20 base slots + 10 backpack slots
```

### Give admins access

The admin panel opens for every player with the ace in `admin.superAce` (default `group.admin`) and for staff added in `data/koja/staff.lua` or the **Permissions** page.

```cfg title="server.cfg"
add_principal identifier.license:YOUR_LICENSE group.admin
add_ace group.admin group.admin allow
```

The second line makes sure the `group.admin` ace check passes for members of the group.
See [Admin panel](/new/inventory/admin-panel#permissions) for roles and per-page access.

### Pick the language

The language comes from ox_lib:

```cfg title="server.cfg"
setr ox:locale "en"
```

English and Polish ship with every string. See [Translations](/new/inventory/translations).

### Restart the server

The `koja_inv_*` tables are created when the resource starts (see [Database](/new/inventory/database)).
There is no SQL file to import.

:::

## Convars

All upstream convars still work. Set them in `server.cfg` with `setr` (client side ones must be replicated, so always use `setr`).

| Convar | Default | What it does |
| --- | --- | --- |
| `inventory:framework` | `"esx"` | Framework bridge: `esx`, `qbx`, `ox` or `nd` |
| `inventory:slots` | `35` | Player slots. Koja splits them into pockets, base slots and backpack slots (see below) |
| `inventory:weight` | `30000` | Player max weight in grams, before backpacks |
| `inventory:target` | `false` | Use ox_target for shops, stashes, crafting benches and evidence instead of markers. ox_target must start first |
| `inventory:keys` | `["F2", "K", "TAB"]` | Default keys: open inventory, open the other inventory (trunk, dumpster...), hotbar |
| `inventory:police` | `["police", "sheriff"]` | Jobs that can use evidence lockers and search players |
| `inventory:networkdumpsters` | `false` | Networked dumpster ids (same contents for everyone) |
| `inventory:dropslots` / `inventory:dropweight` | player values | Size of ground drops |
| `inventory:randomloot` | `true` | Loot in dumpsters and unowned vehicles. The loot tables are edited in the admin panel |
| `inventory:screenblur` | `true` | Blur the game behind the inventory |
| `inventory:itemnotify` | `true` | Item added / removed popups |
| `inventory:imagepath` | `nui://ox_inventory/web/images` | Where item images are loaded from |
| `inventory:enablestealcommand` | `true` | Registers `/steal` |
| `inventory:loglevel`, `inventory:loghookrejection`, `inventory:trimplate`, `inventory:evidencegrade`, `inventory:validhosts` | upstream | Also editable live on the admin **Security** page |

The other upstream convars (`inventory:dropprops`, `inventory:weaponmismatch`, `inventory:autoreload`, `inventory:giveplayerlist`, `inventory:vehicleloot`, `inventory:dumpsterloot`...) keep their ox_inventory meaning.

## Slot layout

With `inventory:slots 35` and the default `baseSlots = 25`, `pockets = 5` in `data/koja/core.lua`:

| Slots | Meaning |
| --- | --- |
| 1–5 | **Pockets** — the hotbar, used with keys 1–5 |
| 6–25 | Always unlocked |
| 26–35 | Locked ("Need a backpack") until a backpack is worn |

`inventory:slots` is the hard maximum. A backpack never unlocks more than that.

## Coming from ox_inventory

Nothing in the database has to change: the `ox_inventory` table, player inventories, stashes, trunks and gloveboxes are read as before.
Keep your `data/items.lua`, `data/shops.lua`, `data/stashes.lua` and `data/crafting.lua` — the format is the same, Koja only adds optional fields.

:::steps

### Back up first

Back up the database and your old `data/*.lua` files.

### Merge your data files

Copy your items, shops, stashes and crafting benches into the new `data/` files.
Add the Koja items you want to keep from the shipped `data/items.lua`: `clothing`, `clothing_hanger`, `backpack_small`, `backpack_large`, `armor_vest`, `plate_light`, `plate_medium`, `plate_heavy`, `tint_1` … `tint_7` (see [Items](/new/inventory/items)).

### Check `inventory:slots`

ox_inventory defaults to 50 slots, Koja to 35. If you keep a higher value, only `baseSlots` (25) are always unlocked; the rest need a backpack.
Raise `baseSlots` in `data/koja/core.lua` if your players should keep more free slots.

### Start and test

Join, open the inventory with **F2**, and open `/invadmin` as an admin.

:::

## Check that it works

1. Press **F2**. The inventory opens with your ped in the middle and the **Inventory**, **Clothing**, **Settings** and **Useful controls** tabs at the top.
2. Your worn clothes appear in **Your clothes** as items (with images when an appearance resource is running).
3. As an admin, type `/invadmin`. The admin panel opens on the Home page.

## Next steps

- [Configuration](/new/inventory/configuration) — slots, clothing, weight, throwing, give, trade, shops and the admin defaults.
- [Admin panel](/new/inventory/admin-panel) — roles, staff and live editing.
- [Troubleshooting](/new/inventory/troubleshooting) — if something above did not happen.