> 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/core/cuxial-admin/configuration.md).

# Configuration

Every option of Cuxial Admin explained: config, convars, starting ranks and the model list.

Behaviour lives in `shared/config.lua`, secrets and access lists in convars, and the starting ranks and model list in `data/`. Restart the resource after any change.

## General

| Option                | Type         | Default      | What it does                                                                                                    |
| --------------------- | ------------ | ------------ | --------------------------------------------------------------------------------------------------------------- |
| `locale`              | string       | `'es'`       | Language of the interface. `'es'` or `'en'`. Notifications and key names follow the `ox:locale` convar instead. |
| `accent`              | string (hex) | configurable | Accent colour of the interface.                                                                                 |
| `announceSeconds`     | number       | `12`         | Seconds a server announcement stays on screen. Minimum 3.                                                       |
| `reportRetentionDays` | number       | `30`         | Days a closed report transcript is kept. Old ones are deleted every day at 04:00. `0` keeps them forever.       |
| `auditRetentionDays`  | number       | `180`        | Days an audit entry is kept. Same daily cleanup. `0` keeps them forever.                                        |

## Commands · `commands`

| Option        | Type   | Default         | What it does                                            |
| ------------- | ------ | --------------- | ------------------------------------------------------- |
| `panel`       | string | `'admin'`       | Command that opens the panel.                           |
| `report`      | string | `'report'`      | Command that opens the report window for players.       |
| `staffReload` | string | `'staffreload'` | Command that reloads ranks and staff from the database. |

## Keys · `keybinds`

| Option         | Type   | Default | What it does                                                               |
| -------------- | ------ | ------- | -------------------------------------------------------------------------- |
| `panel`        | string | `'U'`   | Default key for the panel. `''` registers no key; the command still works. |
| `report`       | string | `''`    | Default key for the report window. `''` registers no key.                  |
| `noclip`       | string | `'END'` | Default key for noclip.                                                    |
| `godmode`      | string | `''`    | Default key for god mode.                                                  |
| `invisible`    | string | `''`    | Default key for invisibility.                                              |
| `infiniteAmmo` | string | `''`    | Default key for infinite ammo.                                             |
| `superJump`    | string | `''`    | Default key for super jump.                                                |
| `blips`        | string | `''`    | Default key for player blips on the map.                                   |
| `names`        | string | `''`    | Default key for names above players.                                       |

{% hint style="info" %}
The seven personal toggles are always registered. With `''` they have no default key and each staff member assigns one in the GTA key settings. A key only works for staff with the matching `self.*` permission.
{% endhint %}

## Names above players · `nameplates`

| Option          | Type   | Default | What it does                                                                                                                                                    |
| --------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `range`         | number | `480.0` | Metres up to which a name is drawn.                                                                                                                             |
| `barRange`      | number | `45.0`  | Metres up to which the health and armour bar is drawn. Beyond it, only the name.                                                                                |
| `cullingRadius` | number | `500.0` | Network radius given to the staff member while names are on, so distant players are loaded. It costs bandwidth for that client. `0.0` keeps the server default. |

## Screen view · `screen`

| Option        | Type    | Default   | What it does                                                                              |
| ------------- | ------- | --------- | ----------------------------------------------------------------------------------------- |
| `width`       | number  | `1280`    | Width of the video in pixels. The height follows the player's screen.                     |
| `fps`         | number  | `24`      | Frames per second.                                                                        |
| `bitrate`     | number  | `4000000` | Bits per second of the video.                                                             |
| `codec`       | string  | `'vp9'`   | `'vp9'` is sharper. `'vp8'` uses less CPU on the player's PC.                             |
| `keyframeMs`  | number  | `10000`   | Milliseconds between full frames.                                                         |
| `audio`       | boolean | `true`    | `true` lets the staff turn on the player's microphone while watching. `false` refuses it. |
| `maxWatchers` | number  | `4`       | Staff members who can watch the same player from inside the game at once.                 |

The screen view also needs convars. See [Convars](#convars).

## Spectate · `spectate`

| Option       | Type    | Default | What it does                                                                                                       |
| ------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `hearVoice`  | boolean | `true`  | `true` lets the staff member hear the target and nearby players while spectating. `false` keeps spectating silent. |
| `hearRadius` | number  | `12.0`  | Metres around the target within which other players are also heard.                                                |

## Limits · `limits`

| Option              | Type   | Default | What it does                                                                                  |
| ------------------- | ------ | ------- | --------------------------------------------------------------------------------------------- |
| `messageLength`     | number | `600`   | Maximum characters of a report message. Longer text is cut.                                   |
| `messageCooldown`   | number | `2000`  | Milliseconds a player must wait between two report messages.                                  |
| `actionCooldown`    | number | `350`   | Milliseconds a staff member must wait between two actions.                                    |
| `messagesPerReport` | number | `150`   | Messages a player can write in one report. Staff replies do not count. `0` removes the limit. |

## Money · `moneyItems`

Maps a money type to an inventory item. When the staff gives a type listed here, the player receives that item. Any type not listed, such as the bank, is added as a framework balance.

| Option        | Type   | Default         | What it does               |
| ------------- | ------ | --------------- | -------------------------- |
| `cash`        | string | `'money'`       | Item given as cash.        |
| `black_money` | string | `'black_money'` | Item given as dirty money. |

## Effects · `effects`

| Option         | Type   | Default | What it does                                                                          |
| -------------- | ------ | ------- | ------------------------------------------------------------------------------------- |
| `drunkSeconds` | number | `30`    | Seconds the drunk effect lasts. Using the action again removes it earlier. Minimum 1. |

## Remote web panel · `remote`

Connects the server to an external web panel service. It only turns on when `enabled` is `true` and both remote convars are set.

| Option      | Type      | Default         | What it does                                                                                                               |
| ----------- | --------- | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `enabled`   | boolean   | `false`         | `true` turns the remote panel on once both remote convars are set. `false` keeps it off, whatever the convars say.         |
| `clockSkew` | number    | `30`            | Seconds of clock difference tolerated between the web panel service and the game server. Requests outside it are rejected. |
| `allowFrom` | string\[] | local addresses | Addresses allowed to send requests. Compared by prefix. An empty list accepts any address.                                 |

{% hint style="danger" %}
Whoever reaches the server's HTTP port and knows the secret acts as staff. Keep the web panel service on the same machine or on a private network, and never empty `allowFrom` on a public server.
{% endhint %}

Even with a valid request, a staff member only gets in from outside when their rank has remote access enabled.

## Convars

All of them are read on the server only. Write them with `set` in `server.cfg`.

| Convar                       | Default | What it does                                                                                                                                        |
| ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cuxial_admin_screen_owners` | empty   | Discord IDs allowed to use the screen view, separated by commas or spaces. Empty turns the feature off for everyone. Read when the resource starts. |
| `sd_phone_relay_url`         | empty   | Address of the media relay. Must start with `ws://` or `wss://`; anything else is ignored.                                                          |
| `sd_phone_relay_key`         | empty   | Key that signs the relay passes. Exactly 64 lowercase hexadecimal characters; anything else is ignored.                                             |
| `sd_phone_relay_ttl`         | `45`    | Seconds a relay pass is valid. Limited to between 10 and 120.                                                                                       |
| `cuxial_admin_remote_url`    | empty   | Address of the web panel service. Read when the resource starts.                                                                                    |
| `cuxial_admin_remote_secret` | empty   | Secret shared with the web panel service. Read when the resource starts.                                                                            |
| `cuxial_admin_debug`         | `0`     | `1` prints every SQL query and its result to the server console. Read when the resource starts.                                                     |

### Screen view

Watching a screen needs three things at once:

1. The staff member's Discord ID is in `cuxial_admin_screen_owners`.
2. Their rank has the `player.screen` permission.
3. `cuxial_bridge` is running. The video goes through its media module.

A rank with every permission still cannot watch screens unless the person is on the list.

The relay is optional:

| Relay                  | Staff inside the game                             | Staff on the web panel  |
| ---------------------- | ------------------------------------------------- | ----------------------- |
| Both relay convars set | Video through the relay                           | Video through the relay |
| Not set                | Video through the game server, at reduced quality | Not available           |

Every viewing and every use of the microphone is written to the audit log.

## Starting ranks · `data/permissions.lua`

This file holds two lists:

* **`catalog`**: the permissions shown in the rank editor, grouped by section. You can change each `label` to translate it. Do not change an `id`: the panel checks those exact values.
* **`seed`**: the ranks created the first time the resource starts, when the ranks table is empty. After that, ranks live in the database and are edited from the panel.

Each seed rank has:

| Field      | Type      | What it does                                                                                           |
| ---------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `id`       | string    | Internal name. Lowercase letters, numbers and `_`.                                                     |
| `label`    | string    | Name shown in the panel.                                                                               |
| `remote`   | boolean   | `true` allows this rank into the remote web panel.                                                     |
| `position` | number    | Order. The lowest number is the highest rank.                                                          |
| `perms`    | string\[] | Permissions granted. See [Commands & permissions](/scripts/core/cuxial-admin/commands.md#permissions). |

## Model list · `data/peds.lua`

The models offered when changing a player's model. Add or remove lines as you like.

```lua
{ id = 'mp_m_freemode_01', label = 'Male (freemode)', sub = 'Customisable' },
```

| Field   | What it does            |
| ------- | ----------------------- |
| `id`    | Model name.             |
| `label` | Name shown in the list. |
| `sub`   | Group shown next to it. |

## Common changes

**Use the panel in English**

{% code title="shared/config.lua" %}

```lua
locale = 'en',
```

{% endcode %}

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

```cfg
setr ox:locale "en"
```

{% endcode %}

**Give cash as a framework balance instead of an item**

Remove the line from `moneyItems`:

{% code title="shared/config.lua" %}

```lua
moneyItems = {
    black_money = 'black_money',
},
```

{% endcode %}

**Turn the remote web panel on**

{% code title="shared/config.lua" %}

```lua
remote = {
    enabled = true,
    clockSkew = 30,
    allowFrom = { '127.0.0.1', '::1', 'localhost' },
},
```

{% endcode %}

**Forbid listening to the microphone during the screen view**

{% code title="shared/config.lua" %}

```lua
screen = {
    -- other options unchanged
    audio = false,
},
```

{% endcode %}


---

# 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/core/cuxial-admin/configuration.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.