Installation Guide

This guide takes you from a fresh download to a working phone. Every step says what to do and what you should see when it worked. You don't need to know any Lua. The only files you open are server.cfg, the item file of your inventory, and (optionally) the phone's settings file.

What's in the Package

Buying Oxide Phone gives you four resources (a resource is one folder your server starts). Each is its own download in your Cfx Portal assets, under the name below:

The three apps are optional. Each one works on its own, so you can install all three, some of them, or none. An app does nothing without oxide-phone. Each app has its own guide for its settings: Hookr, Leakd and Glitch.

Prerequisites

Required Resources

These must be installed and running. Most servers already run ox_lib and oxmysql.

OneSync must be turned on. The server reads where players stand to decide who hears a phone ring, who is close enough to share a contact, who is in a no-signal area and where a traced phone is. Most servers already have OneSync on. If yours doesn't, add set onesync on to your server.cfg.

That is everything the phone needs. Every other resource on this page is optional.

Supported Frameworks

Everything goes through o-link, so you install one copy of the phone and it works on whichever framework you run.

Optional Resources

The phone works without every one of these. Each one adds something when it runs. Integrations describes each one in full.

Installation Steps

Load Order

Every Oxide resource uses the same four-part order in server.cfg:

# 1. Framework — everything your framework requires (qb-core, es_extended, qbx_core, etc.)
ensure <framework>

# 2. Scripts — your other resources (phone, inventory, garages, etc.)
ensure <your-other-scripts>

# 3. o-link — the bridge. Starts after your framework/scripts, before any Oxide resource.
ensure o-link

# 4. Oxide resources — keep these together, ideally in a folder named [oxide]
ensure oxide-phone
ensure oxide-hookr
ensure oxide-leakd
ensure oxide-glitch

• ox_lib and oxmysql go anywhere above o-link (part 1 or 2). Most frameworks already start them in part 1.
• Your inventory, pma-voice, your target resource and your dispatch resource belong in part 2, above o-link. o-link looks for them at the moment it starts.
• Don't put oxide-phone or the apps above o-link. They list o-link as something they need, so starting one of them first makes the server start o-link early, before your framework. o-link then can't find your framework, and nothing works properly.
• Leave out the line of any app you didn't install. The phone works without all three.
• List the phone before the apps, as above. Each app finds the phone whichever starts first, so nothing breaks if the order differs, but this order matches each app's own guide (Hookr, Leakd, Glitch).
• If your Oxide resources are in an [oxide] folder, one ensure [oxide] line in part 4 starts them all. Within part 4 the order doesn't matter.
• If you add or restart o-link while the server is running, restart oxide-phone and the apps afterwards too. Restarting the whole server is the safest option.

Framework Setup

The Items

The phone uses five items. They must exist in your inventory with the names below. You can rename any of them later in game with /phone settings (Items). Hookr, Leakd and Glitch need no items of their own.

Using a SIM card or powerbank puts it into (or charges) the phone that is open, or, if no phone is open, the phone in your lowest inventory slot.

The phone item must not stack. Each phone saves its device ID on the item. Stacked phones would share one device.

Inventories and Item Data

Some inventories can save extra information on an item (this is called item data or metadata). The phone uses it to remember which device a phone item is, and which number a SIM card that was taken out belongs to.

With any other inventory o-link supports, the phone finds out the first time a phone is used and prints one line in the server console saying which way it went (see Verification).

ox_inventory (QBX, and QBCore or ESX servers using ox_inventory)

1. Open items/ox_inventory_items.lua in the oxide-phone folder.
2. Copy every line between return { and the final }.
3. Open ox_inventory/data/items.lua. Delete its existing ['phone'] entry. The stock one calls another phone script (npwd) when the item is added or removed.
4. Paste the copied lines just above the file's final closing }.
5. Save the file.

Use the entries exactly as they are in the template. If your file already has one of these item names from another script, keep only the phone's copy.

QBCore (qb-inventory)

1. Open qb-core/shared/items.lua.

2. Find the existing phone line and replace it with the first line below. Then add the other four lines:

   phone       = { name = 'phone',       label = 'Phone',       weight = 190, type = 'item', image = 'phone.png',       unique = true,  useable = true,  shouldClose = true, description = 'A smartphone' },
   sim_card    = { name = 'sim_card',    label = 'SIM Card',    weight = 5,   type = 'item', image = 'sim_card.png',    unique = true,  useable = true,  shouldClose = true, description = 'A SIM card registered to your name' },
   burner_sim  = { name = 'burner_sim',  label = 'Burner SIM',  weight = 5,   type = 'item', image = 'burner_sim.png',  unique = true,  useable = true,  shouldClose = true, description = 'A SIM card registered to nobody' },
   powerbank   = { name = 'powerbank',   label = 'Powerbank',   weight = 150, type = 'item', image = 'powerbank.png',   unique = false, useable = true,  shouldClose = true, description = 'Charges a phone once' },
   phone_wiper = { name = 'phone_wiper', label = 'Phone Wiper', weight = 30,  type = 'item', image = 'phone_wiper.png', unique = false, useable = false, shouldClose = true, description = 'Wipes a phone so nothing on it can be recovered' },

3. Save the file.

ESX Without an Inventory Resource

Most ESX servers run ox_inventory. If yours does, follow ox_inventory above instead.

ESX's own item list keeps its items in the database. Run this in your database manager (the program you use to look at your server's database, such as HeidiSQL, phpMyAdmin, or the database page in your hosting panel). It only adds items that are missing:

INSERT IGNORE INTO `items` (`name`, `label`, `weight`) VALUES
    ('phone', 'Phone', 1),
    ('sim_card', 'SIM Card', 1),
    ('burner_sim', 'Burner SIM', 1),
    ('powerbank', 'Powerbank', 1),
    ('phone_wiper', 'Phone Wiper', 1);

On ESX's own item list the phone opens, and every character gets one phone and a registered number the first time they use it. SIM cards, powerbanks and the phone wiper need an inventory resource o-link supports (for example ox_inventory): without one, using them does nothing.

Item Icons

Icons for all five items ship in the items/ folder: phone.png, sim_card.png, burner_sim.png, powerbank.png and phone_wiper.png. Copy the five .png files into your inventory's image folder:

Both inventories already have a phone.png for their stock phone item. Let the copy replace it: the new icon shows this phone.

Without an icon the item still works; it just shows a blank picture.

Database Setup

You don't need to import anything. The phone creates all its tables the first time it starts. They all start with oxide_phone_, apart from the shared settings table:

Each app creates its own tables the first time it starts: their names start with oxide_hookr_, oxide_leakd_ and oxide_glitch_. The same tables are in each app's sql/migrations/ folder. The apps check their tables at every start, so the database user your server connects with (the one in your oxmysql connection line) must be allowed to create tables for the apps to work.

If your database user isn't allowed to create tables, set the phone's tables up by hand once with your database manager:

1. Import sql/install.sql from the oxide-phone folder.
2. Import every file in oxide-phone/sql/migrations/, in number order (0001 first). Some lines fail with a message that a column, key or table already exists. That is expected: that part is already done. Skip that line and run the rest of the file.

Running these files on a database that already has the tables does no harm: lines for parts that are already done either do nothing or fail, and you skip the ones that fail. When an update adds tables or columns, the phone adds them itself at start; a database user that can't do that imports the new files in sql/migrations/ the same way.

Configure Before the First Start

You don't have to edit the file at all. Every setting can be changed in game after the first start, and most changes apply straight away. If you like to prepare things first, Configuration lists every setting.

Server Convars

A convar is a setting line in server.cfg. The phone reads these:

Keys stay on your server. They are never sent to players. After changing a convar, restart the server (or restart oxide-phone in the server console).

Calls

Calls need pma-voice with phone calls turned on, which is its default. If your server.cfg sets voice_enablePhones, it must be 1:

setr voice_enablePhones 1

Without pma-voice the phone still works: texts, contacts, mail and notifications are unaffected, and the Phone app tells players that calls are not available on this server.

A ringing phone can be heard by players standing near it. Players who turn the sound off or use Do Not Disturb on their phone ring silently. The ring sound, its range and the ring time are in /phone settings (Calls & Messages).

Voicemail uses the same storage as photos (see Photos). Without storage, callers can't leave a message and the rest of calling works as normal. Players record voicemail with their microphone.

Photos

The phone does not store photos or videos itself. Until you pick a storage service, the Camera app says that photos are not set up; everything else works. Pick one in /phone settings (Media → Photo storage) and put its key in server.cfg. The same storage and key hold videos and voice clips; there is nothing separate to set up for them.

The apps use the phone's storage too. Without it, players can't add photos to a Hookr profile (which needs at least one), can't post photos or videos on Leakd, and Glitch channels keep plain initials instead of pictures. Live streams on Leakd and Glitch don't use storage: the video goes through your game server (see Apps).

Fivemanage

1. Create a media API key in your Fivemanage dashboard.

2. Add it to server.cfg:

   set oxide_phone_fivemanage_key "your-key"

   If your server.cfg already has set FIVEMANAGE_MEDIA_API_KEY "..." for other scripts, skip this step. The phone uses that key.

3. Restart your server.

4. In /phone settings → Media, set Storage to Fivemanage and press Save Changes.

S3 or R2 Compatible Storage

1. Create a bucket and an access key that can write to it. Serve the bucket from a public https:// address (for Cloudflare R2, a custom domain or the public r2.dev address).

2. Add the keys to server.cfg:

   set oxide_phone_s3_access_key "your-access-key-id"
   set oxide_phone_s3_secret_key "your-secret-key"

3. Restart your server.

4. In /phone settings → Media, set Storage to S3 or R2 compatible and fill in:

   • Endpoint, starting with https:// (for example https://<account-id>.r2.cloudflarestorage.com)
   • Region (auto for R2)
   • Bucket
   • Public address, the https:// address the bucket is served from (for example https://photos.example.com)

5. Allow uploads from the game in the bucket's CORS settings: origin https://cfx-nui-oxide-phone, method PUT, header Content-Type. Videos use the same rule. Also allowing method GET lets Photos read files directly for editing; without it the server fetches them instead, which is slower.

Other Storage

Set Storage to Custom and have a resource of your own hand out upload addresses (see Building Apps → Custom photo storage). Add the host your photos are served from under Allowed hosts.

Photos and videos are only ever shown from the storage hosts you configured. An address anywhere else is refused when it is saved and never shown.

Police and Evidence

Police can seize a phone, get a search authorization, extract what is on it, read carrier records and trace a number, all in the Forensics app, which police see on their phone. Nothing else needs to be installed. Set it up in /phone settings → Evidence:

1. Police jobs: your police job names (as your framework spells them) and the lowest grade that counts.
2. Authorizers: who issues search authorizations, for example police command or a judge job.
3. Forensics stations (optional): places where police extract a phone they carry. Add a row, press the crosshair button (Place in world) and pick the spot in the world, then set its Reach. Turn on Extract only at a station if extraction should not work anywhere else.

Must be on duty is on by default. It applies to police and to authorizers: a job with no duty system can't issue authorizations while it is on.

When oxide-police runs, every extraction report is also attached to the case the officer names, and an active warrant for the phone's owner counts as a search authorization. To send reports to another MDT, or to decide authorizations with your own system, see Evidence Bridge.

Emergency Numbers

Dialling 911 or 311 in the Phone app (or pressing Emergency call on the lock screen) sends the call to your dispatch system:

• With oxide-dispatch, calls arrive as its 911/311 calls with the caller's number, and replies from responders arrive on the caller's phone as texts.
• With another dispatch resource, the call arrives as a normal alert.
• With no dispatch resource at all, players with the jobs listed for the number get a notification and a map blip for 30 seconds.

Change the numbers and jobs in /phone settings → Emergency.

Apps

The phone brings its own apps, set up in /phone settings → Apps:

• Notes, Calculator and Clock need no setup. The Clock's timer goes off even with the phone put away.
• Maps shows o-link's shared map (the same one oxide-tablet uses). Players tap to set a waypoint, and Share my location sends where they stand as a text. Choose how the map shows Cayo Perico with Map mode in /phone settings → General, or with oxide-phone:mapmode (see Admin).
• Wallet shows the bank balance from your framework and sends and requests money by phone number. The money goes to the character the number is registered to, so a burner SIM cannot receive it. Set the largest transfer and the daily limit in Apps → Wallet. When oxide-banking runs, its own Banking app appears in the Store, and Wallet stays beside it.
• Dark Chat and Feed are in the Store. In Dark Chat players pick a handle and nobody sees their number. In Feed, admins can delete any post, mute an author for 24 hours, verify handles and work through reported posts.

With the gig jobs (pizza, landscaping, postal, roadside, animal control, newspaper, pest control) and their usePhone setting on, the Gigs app appears on the phone and their shift updates and job calls arrive as Gigs notifications. With Apps → Gigs off, the updates arrive as texts from the job instead. See Integrations.

Hookr, Leakd and Glitch

Each app you installed shows up in the phone's Store, and players get it there. To put an app on every phone instead (players can't remove it):

1. Type /phone settings in game.
2. Open Home & Apps → Store.
3. Add the app's id under Preinstalled apps: hookr, leakd or glitch.
4. Press Save Changes.

Each app's own settings are in its own folder. See Hookr, Leakd and Glitch, and their installation guides: Hookr, Leakd and Glitch.

Live Streams

Leakd and Glitch let players go live with the phone's camera. The video goes from the streamer's game through your server to every viewer, so there is nothing extra to set up, but each viewer uses your server's upload: about 0.73 Mbps at the default quality, so 25 viewers use about 18 Mbps. The phone sets the limits for every app together in /phone settings → Media → Live streams: 25 viewers per stream, 4 streams at once and 40 Mbps of upload by default. Lower them if your server's connection is slow. See Configuration → Live Streams.

Custom Wallpapers (Optional)

The phone has five built-in wallpapers. To add your own:

A full https:// web address also works as the Image, without a file. Plain http:// addresses are not accepted.

Keep an image's Id the same once players have picked it. If you change or remove it, those phones go back to the default wallpaper.

Wallpapers from links. Players can also paste an image link in Settings → Wallpaper → From a Link, but only from sites you approve. In /phone settings, open Home & Apps → Home screen and add each site under Approved wallpaper links, for example images.example.com (its subdomains count too) or an address links must start with, such as https://cdn.example.com/wallpapers/. Leave the list empty to turn this off. See Configuration → Home Screen.

Translations

All player-facing text is in locales/en.json. To translate the phone:

1. Copy locales/en.json to a new file named after your language code, for example locales/de.json.
2. Translate the text on the right side of each line. Keep the %s markers: they are filled in with names, numbers and times.
3. Set ox_lib's language in server.cfg, for example setr ox:locale de, and restart the server.

The /phone settings menu is English only.

Admin Access

The admin parts of the phone (/phone settings, the other /phone commands and Feed moderation) use o-link's admin check. A player passes if they have the admin or command permission. On ESX, members of an ESX admin group pass too.

• Most QBCore and QBX servers already give their group.admin group the command permission in server.cfg, so existing admins work straight away.

• Otherwise, add these two lines to your server.cfg, replacing YOUR_LICENSE with the admin's license identifier:

  add_principal identifier.license:YOUR_LICENSE group.admin
  add_ace group.admin admin allow

The full command list is in Admin.

Updating

1. Replace the folders with the new versions from your Cfx Portal assets: oxide-phone and each app you use. Each one is updated on its own. Your settings and players' data are in the database, so you lose nothing.
2. Restart the whole server. A running server keeps an old list of each resource's files until refresh is typed in the server console, so a plain restart oxide-phone after an update can run with parts missing. A full restart avoids that. If you must update without one, type refresh first, then restart oxide-phone and restart each app.
3. Update o-link too when the phone's update asks for a newer one.

New tables and columns are added by the phone and the apps themselves when they start.

Verification

[INFO][oxide-phone][lifecycle] phone ready

/giveitem YOUR_ID phone 1

If any step doesn't match what you see, go to Troubleshooting.

Next Steps