Installation
Follow these steps in order. No SQL import and no items are needed.
Before you start
Section titled “Before you start”Check that you have:
- A server artifact 6116 or newer, with OneSync enabled.
oxmysql(2.7.3 or newer) andox_lib(3.27.0 or newer) installed.- One of the supported frameworks running: ESX (
es_extended), QB-Core (qb-core), QBX (qbx_core) or OX Core (ox_core). - No other inventory resource that you still want to run. Only one resource can be named
ox_inventory. If you already have one, read Migrating from stock ox_inventory first.
1. Copy both folders
Section titled “1. Copy both folders”Copy the two folders from the download into your server’s resources folder (or into a category folder inside it):
resources/ [kivo]/ <- optional category folder, any name in square brackets kivo-inv-bridge/ fxmanifest.lua shared/ client/ server/ ox_inventory/ fxmanifest.lua client.lua server.lua data/ locales/ web/ ...Keep both folder names exactly as they are. Do not rename kivo-inv-bridge: the inventory looks for a resource with that exact name.
Do not move files from ox_inventory into the root of your resources folder. All Kivo files stay inside the ox_inventory folder.
2. Check the interface files
Section titled “2. Check the interface files”The interface is shipped pre-built. The file ox_inventory/web/build/index.html must exist, otherwise ox_inventory refuses to start and prints an error saying the UI has not been built.
If your download has a build.zip file inside ox_inventory/web/ instead of a build folder, extract it there so that the result is:
ox_inventory/ web/ build/ index.html assets/The file node_modules.zip in ox_inventory/web/ is only used to rebuild the interface. You do not need it on a live server and can delete it.
3. Add the resources to server.cfg
Section titled “3. Add the resources to server.cfg”Start the dependencies first, then your framework, then the bridge, then ox_inventory:
# Settings read by ox_inventory (set these above the ensure lines)setr inventory:framework "esx"
# Dependenciesensure oxmysqlensure ox_lib
# Your framework (keep only the one you run)ensure es_extended# ensure qb-core# ensure qbx_core# ensure ox_core
# Optional, only if you use inventory:target 1# ensure ox_target
# Kivo Inventory: the bridge MUST come before ox_inventoryensure kivo-inv-bridgeensure ox_inventorySet inventory:framework to the framework you run. The framework modules shipped in ox_inventory/modules/bridge/ are esx, ox, nd and qbx. This setting belongs to ox_inventory. The bridge is separate: it detects the framework on its own. See Configuration.
If you already have ensure ox_inventory somewhere in your server.cfg, keep only one line and put ensure kivo-inv-bridge directly above it.
4. Set up avatars (optional)
Section titled “4. Set up avatars (optional)”The bridge shows Discord or Steam profile pictures. Open kivo-inv-bridge/shared/config.lua and fill in a Discord bot token, a Steam Web API key, or both. Replace any value that is pre-filled in the file with your own.
Without any of these, everything still works and players see the default profile picture. All options are explained in Configuration.
5. Start the server and check
Section titled “5. Start the server and check”Restart the server. In the server console you should see one of these lines from the bridge:
[kivo-inv-bridge] Detected framework: ESX[kivo-inv-bridge] Detected framework: QBX[kivo-inv-bridge] Detected framework: QB-Core[kivo-inv-bridge] Detected framework: OX CoreThen join the server and open your inventory (F2 by default). Check that:
- The inventory opens and shows the Kivo interface.
- The top of your inventory shows your RP name, your ID, and your cash and bank amounts.
- Your avatar appears if you set up Discord or Steam, otherwise the default picture.
If the line WARNING: No supported framework detected! appears, your framework was not started yet when the bridge started. Move your framework ensure line above ensure kivo-inv-bridge. More fixes are in Examples and troubleshooting.
Migrating from stock ox_inventory
Section titled “Migrating from stock ox_inventory”Use this when your server already runs ox_inventory and you want to switch to Kivo Inventory. Kivo is based on ox_inventory 2.44.1 and keeps its data layout, so your existing inventories stay in the database.
- Stop the server (or at least stop
ox_inventory). - Back up. Copy your current
ox_inventoryfolder to a place outsideresources. Also back up your database, because ox_inventory stores player, stash and vehicle inventories there. - Note your version. Open your current
ox_inventory/fxmanifest.luaand read theversionline. Kivo is based on2.44.1. If your version is different, look at the upstream ox_inventory changelog for changes in thedatafiles before you copy them over. - Remove the old folder. Move your old
ox_inventoryout ofresourcesso only the Kivo one remains. - Copy the two Kivo folders (
kivo-inv-bridgeandox_inventory) intoresources, as in step 1 above. - Check the interface files (step 2 above).
- Carry over your own changes. Copy these from your backup into the new
ox_inventoryfolder:- Your edited files in
data/(items, weapons, shops, stashes, crafting, vehicles and so on). - Your edited files in
locales/, if you changed any. - Extra item images you added to
web/images/. - Edits you made inside
modules/, if any.
- Your edited files in
- Do not copy back
client.lua,server.lua,init.lua,fxmanifest.luaor anything inweb/from your backup. They would overwrite the Kivo interface and its callbacks. If you made code changes inclient.luaorserver.lua, re-apply them by hand into the Kivo files. - Keep your convars. Your existing
setr inventory:*lines inserver.cfgstay as they are. - Edit
server.cfg. Addensure kivo-inv-bridgedirectly aboveensure ox_inventory(step 3 above). - Start the server and run the checks from step 5.
To go back to stock ox_inventory, stop the server, put your backed up folder back, and remove the ensure kivo-inv-bridge line.
Updating to a new Kivo release
Section titled “Updating to a new Kivo release”Updating works like a migration. Before you replace the folders, save:
kivo-inv-bridge/shared/config.lua(your avatar settings).- Your edited files in
ox_inventory/data/,ox_inventory/locales/andox_inventory/web/images/. - Any change you made to
ox_inventory/client.lua, for example if you changed one of the interface callbacks as shown in Exports and integration.
Then replace both folders, restore your files, and keep the bridge above ox_inventory in server.cfg. If players still see the old interface after the update, ask them to restart FiveM. You can also clear the server cache folder and restart the server.
Using the Kivo interface with your own ox_inventory
Section titled “Using the Kivo interface with your own ox_inventory”Use this only if you run a modified ox_inventory that you cannot replace with the Kivo folder. The interface was built for ox_inventory 2.44.1. If your version is very different, ask Kivo support before you try this.
-
Back up your current
ox_inventoryfolder. -
Copy
kivo-inv-bridgeintoresourcesand start it beforeox_inventory(step 3 above). -
Replace your
ox_inventory/web/build/folder with the Kivoweb/build/folder. Replace the whole folder. Do not mix files from the stock build and the Kivo build. -
Open the Kivo
ox_inventory/client.luaand find the four callbacks that sit between theuiLoadedcallback and thegetItemDatacallback. The first one isgetBalances. Copy this whole block into your ownclient.lua, at file level, for example directly after youruiLoadedcallback. Do not change or remove any of the four. -
Make sure your
fxmanifest.luapoints to the new build:ui_page 'web/build/index.html'files {'web/build/index.html','web/build/**/*','web/images/*.png',}Keep the other entries your
fileslist already has. -
Restart the server and run the checks from step 5. The callbacks print
[kivo-inv]lines in the F8 console while you test. This is normal.
Rebuilding the interface (optional)
Section titled “Rebuilding the interface (optional)”You only need this if you edit the interface source in ox_inventory/web/src, for example to change the $ currency symbol. You need Node.js 20.19 or newer.
cd ox_inventory/webnpm installnpm run buildThe build writes the finished interface to ox_inventory/web/build/, which is the folder fxmanifest.lua points to. Restart ox_inventory afterwards. Keep a copy of your source changes, because a new Kivo release replaces web/src.
