> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Drop-in replacement for ox_inventory - same folder, same exports.

<Warning>
  **This guide assumes you already run `ox_inventory` on your server.** Awoken Inventory is a drop-in replacement - same folder name, same database schema, same exports. If you've never installed ox\_inventory before, set up stock ox\_inventory first using the upstream Overextended guide, confirm it works, then come back here to swap it for the Awoken build.
</Warning>

<Card title="First-time install? Use the upstream guide first." icon="link" href="https://overextended.dev/ox_inventory">
  Convars, framework selection, database schema, hotbar setup, dependencies - all covered in the official Overextended documentation. Get stock ox\_inventory running, then replace it with this build.
</Card>

## Asset download

<Info>
  To find the asset, you must have made the purchase using your own keymaster account. Otherwise, you can use the transfer system to move the asset to a different keymaster account.
</Info>

Once the purchase is made on our official website, you will receive your asset directly in your [Cfx.re portal](https://portal.cfx.re/). Download it from your panel.

## Back up your existing ox\_inventory

<Warning>
  **Do this before anything else.** Replacing the folder without a backup means any custom items, weapons, shops, stashes, recipes, images, or other edits you made to your current ox\_inventory will be **gone**.
</Warning>

Copy the entire `ox_inventory` folder somewhere safe - outside the `resources/` directory. You will need to manually port your customisations into the new build (see [Porting your customisations](#porting-your-customisations) below).

## Install steps

<Steps>
  <Step title="Stop the server" />

  <Step title="Replace the folder">
    Delete (or move out) the existing `ox_inventory` folder, then extract the Awoken build into the same path. **The folder name must stay `ox_inventory`** - every dependent resource on your server references it.
  </Step>

  <Step title="Port your customisations">
    Copy your custom items, weapons, shops, stashes, recipes, images, and any other edits from your backup into the new folder. See [Porting your customisations](#porting-your-customisations) below for the file map.
  </Step>

  <Step title="(Optional) Set the global accent colour convar">
    Add this single line to `server.cfg` if you want one convar to theme every Awoken-branded resource on the server:

    ```cfg server.cfg theme={"dark"}
    setr awoken:primaryColor "#00E5FF"
    ```

    When set, it overrides `accentColor` in `config.json`. Leave it unset to use the per-resource value. **This is the only Awoken-specific convar.** Every other ox\_inventory convar is the standard upstream one - see the [Overextended docs](https://overextended.dev/ox_inventory) for those.
  </Step>

  <Step title="Start the server">
    `ensure ox_inventory` as normal. The schema is unchanged from upstream, so no SQL migration runs.
  </Step>
</Steps>

## Migration

The files most servers customise live in these locations. Copy your edits from the backup into the same paths in the new install.

| What you customised    | File in your backup → File in the new install |
| ---------------------- | --------------------------------------------- |
| Custom items           | `data/items.lua`                              |
| Custom weapons         | `data/weapons.lua`                            |
| Custom shops           | `data/shops.lua`                              |
| Custom stashes         | `data/stashes.lua`                            |
| Custom recipes         | `data/crafting.lua`                           |
| Custom vehicle storage | `data/vehicles.lua`                           |
| Custom licences        | `data/licenses.lua`                           |
| Custom animations      | `data/animations.lua`                         |
| Custom evidence types  | `data/evidence.lua`                           |
| Item images            | `web/images/*.png`                            |
| Locale overrides       | `locales/*.json`                              |

<Tip>
  When porting items and weapons, take the opportunity to add `rarity` and `tags` fields - they're optional, but they're what unlocks the Awoken rarity glow and tag filter in the UI. See [Rarity](/configuration/rarity) and [Tags](/configuration/tags).
</Tip>

<Info>
  If you previously stored extra `data/` files of your own, copy those across too. The Awoken rework adds **one** new data file of its own - `data/containers.lua` - so don't be surprised to see it in the new install. Leave it alone unless you want to define your own [containers](/configuration/containers).
</Info>

## Verifying the install

After starting the server:

* Open the inventory (default **TAB**). The Awoken UI should render with your accent colour.
* Hover an item that has a `rarity` field - its slot should glow in the tier colour and the tooltip should show a rarity badge.
* Open the filter toolbar at the top of the inventory - Sort, Rarity, and Type chips should be present.
* Check the server console - there should be no errors from `ox_inventory` during startup.

If something doesn't look right, the most common cause is a stale NUI cache - restart the resource (`ensure ox_inventory`).

## Updating

Re-download the asset from your Cfx.re portal, repeat the **Back up** and **Replace the folder** steps above, then re-apply any edits you made to the user-editable `data/*.lua` files and `web/images/`.