Skip to content

Installation

Follow these steps in order. No SQL import and no items are needed.

Check that you have:

  • A server artifact 6116 or newer, with OneSync enabled.
  • oxmysql (2.7.3 or newer) and ox_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.

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.

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.

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"
# Dependencies
ensure oxmysql
ensure 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_inventory
ensure kivo-inv-bridge
ensure ox_inventory

Set 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.

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.

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 Core

Then 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.

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.

  1. Stop the server (or at least stop ox_inventory).
  2. Back up. Copy your current ox_inventory folder to a place outside resources. Also back up your database, because ox_inventory stores player, stash and vehicle inventories there.
  3. Note your version. Open your current ox_inventory/fxmanifest.lua and read the version line. Kivo is based on 2.44.1. If your version is different, look at the upstream ox_inventory changelog for changes in the data files before you copy them over.
  4. Remove the old folder. Move your old ox_inventory out of resources so only the Kivo one remains.
  5. Copy the two Kivo folders (kivo-inv-bridge and ox_inventory) into resources, as in step 1 above.
  6. Check the interface files (step 2 above).
  7. Carry over your own changes. Copy these from your backup into the new ox_inventory folder:
    • 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.
  8. Do not copy back client.lua, server.lua, init.lua, fxmanifest.lua or anything in web/ from your backup. They would overwrite the Kivo interface and its callbacks. If you made code changes in client.lua or server.lua, re-apply them by hand into the Kivo files.
  9. Keep your convars. Your existing setr inventory:* lines in server.cfg stay as they are.
  10. Edit server.cfg. Add ensure kivo-inv-bridge directly above ensure ox_inventory (step 3 above).
  11. 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 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/ and ox_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.

  1. Back up your current ox_inventory folder.

  2. Copy kivo-inv-bridge into resources and start it before ox_inventory (step 3 above).

  3. Replace your ox_inventory/web/build/ folder with the Kivo web/build/ folder. Replace the whole folder. Do not mix files from the stock build and the Kivo build.

  4. Open the Kivo ox_inventory/client.lua and find the four callbacks that sit between the uiLoaded callback and the getItemData callback. The first one is getBalances. Copy this whole block into your own client.lua, at file level, for example directly after your uiLoaded callback. Do not change or remove any of the four.

  5. Make sure your fxmanifest.lua points 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 files list already has.

  6. 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.

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.

Terminal window
cd ox_inventory/web
npm install
npm run build

The 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.