> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/getting-started/cuxial-bridge.md).

# Cuxial Bridge

The compatibility layer every Cuxial script uses to talk to your framework, inventory and target.

Cuxial Bridge lets one script run on QBox, QBCore or ESX without editing it. Scripts ask the bridge for players, money, jobs, items and target options; the bridge translates each request to whatever your server runs.

It is free and open source. Every Cuxial script requires it, and you install it once.

## What it supports

| Layer     | Supported                                      | Detected by                          |
| --------- | ---------------------------------------------- | ------------------------------------ |
| Framework | QBox, QBCore, ESX                              | `qbx_core`, `qb-core`, `es_extended` |
| Inventory | `ox_inventory`, `qb-inventory`                 | Resource with that name              |
| Target    | `sleepless_interact`, `ox_target`, `qb-target` | Resource with that name              |

Detection follows the order of each row. If two options are running, the first one wins: `qbx_core` over `qb-core`, `ox_inventory` over `qb-inventory`, `sleepless_interact` over `ox_target`.

If nothing is detected, the bridge falls back to QBox, `ox_inventory` and `ox_target`.

{% hint style="info" %}
Some scripts require a specific framework: Cuxial Multichar requires QBox or QBCore. Each script's page lists its requirements.
{% endhint %}

## Installation

{% stepper %}
{% step %}

## Install the dependency

Cuxial Bridge needs `ox_lib`. Make sure it is installed and starts before the bridge.
{% endstep %}

{% step %}

## Copy the resource

Download the latest release from [GitHub](https://github.com/Cuxialv2/cuxial_bridge/releases/latest) and place the `cuxial_bridge` folder in your `resources` directory. Every version and its changes are listed on the [releases page](https://github.com/Cuxialv2/cuxial_bridge/releases).

{% hint style="danger" %}
Keep the folder name `cuxial_bridge`. Every script loads it by that exact name and will fail to start if you rename it.
{% endhint %}
{% endstep %}

{% step %}

## Start it after your framework

Add it below your framework, inventory and target, and above every Cuxial script.

{% code title="server.cfg" %}

```cfg
ensure ox_lib
ensure qbx_core
ensure ox_inventory
ensure ox_target

ensure cuxial_bridge
```

{% endcode %}

Replace the framework, inventory and target lines with the ones your server uses.
{% endstep %}

{% step %}

## Check the server console

On start, the bridge prints what it detected:

```
[cuxial_bridge] listo framework=qbox inventario=ox_inventory target=ox_target contexto=server
```

If the three values match your server, you are done.
{% endstep %}
{% endstepper %}

## Configuration

Cuxial Bridge has no configuration file. You only need the convars below when detection picks the wrong option.

### Forcing a choice

| Convar                    | Default | Values                                                 |
| ------------------------- | ------- | ------------------------------------------------------ |
| `cuxial_bridge:framework` | `auto`  | `auto`, `qbox`, `qbcore`, `esx`                        |
| `cuxial_bridge:inventory` | `auto`  | `auto`, `ox_inventory`, `qb-inventory`                 |
| `cuxial_bridge:target`    | `auto`  | `auto`, `sleepless_interact`, `ox_target`, `qb-target` |

{% code title="server.cfg" %}

```cfg
setr cuxial_bridge:framework "esx"
setr cuxial_bridge:inventory "ox_inventory"
setr cuxial_bridge:target "ox_target"
```

{% endcode %}

{% hint style="warning" %}
Use `setr`, not `set`. These values are read on the server and on each player's game; with `set` the two sides can disagree. Place the lines above `ensure cuxial_bridge`.
{% endhint %}

### Custom database tables

Change these only if your framework stores characters or vehicles in tables with different names. They are read on the server only, so `set` is enough.

| Convar                         | QBox / QBCore default | ESX default      | What it is                  |
| ------------------------------ | --------------------- | ---------------- | --------------------------- |
| `cuxial_bridge:charTable`      | `players`             | `users`          | Characters table            |
| `cuxial_bridge:charIdColumn`   | `citizenid`           | `identifier`     | Character identifier column |
| `cuxial_bridge:vehTable`       | `player_vehicles`     | `owned_vehicles` | Owned vehicles table        |
| `cuxial_bridge:vehOwnerColumn` | `citizenid`           | `owner`          | Vehicle owner column        |

{% code title="server.cfg" %}

```cfg
set cuxial_bridge:charTable "players"
```

{% endcode %}

## Updates

When the server starts, Cuxial Bridge checks GitHub for a newer release. If there is one, it prints a notice in the server console with the new version number, a summary of the changes and the download link. Nothing is downloaded or changed automatically.

To update, download the [latest release](https://github.com/Cuxialv2/cuxial_bridge/releases/latest), replace the `cuxial_bridge` folder and restart the server.

Update the bridge before updating a script: new script versions can rely on the latest bridge. See [Updating a script](/scripts/getting-started/updating.md).

## Common problems

<details>

<summary>The console shows a warning that no framework was detected</summary>

The warning reads `[cuxial_bridge] aviso: no se detectó framework, usando fallback "qbox"`.

**Cause.** Your framework was not running when the bridge, or a script, loaded.

**Fix.** Move the framework `ensure` line above `cuxial_bridge` and above every Cuxial script. If the framework resource has a non-standard folder name, force it with `setr cuxial_bridge:framework`.

</details>

<details>

<summary>The wrong inventory or target is detected</summary>

**Cause.** Two options are running at the same time, or yours starts after the Cuxial scripts.

**Fix.** Check the start order first. If both resources must stay, force the right one with `setr cuxial_bridge:inventory` or `setr cuxial_bridge:target`.

</details>

<details>

<summary>A script fails to start with an error mentioning cuxial_bridge/init.lua</summary>

**Cause.** The bridge is missing, was renamed, or starts after the script.

**Fix.** Confirm the folder is named `cuxial_bridge` and that `ensure cuxial_bridge` appears before the script.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cuxial.com/scripts/getting-started/cuxial-bridge.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.