Free Phone

Free Phone is a complete FiveM smartphone with an iPhone-inspired Sky UI, persistent devices, physical or virtual SIM cards, calls, messages, social networks, media apps, server services, games, and custom-app compatibility.

Requirements

Start the selected framework, inventory, and voice resources before sky_phone.

Free Phone uses its own framework bridge and file storage. It does not require sky_base or an add_filesystem_permission sky_base write sky_phone entry. For other Sky resources installed on the same server, follow Filesystem permissions.

Phone requires its own administrator ACE setup. Permissions granted to Sky Base do not grant Phone permission to register its command access.

Install the resource

Config.PhoneConfigurator = {
    Enabled = true,
}

add_ace resource.sky_phone command.add_ace allow
add_ace resource.sky_phone command.remove_ace allow

ensure oxmysql
ensure es_extended
ensure ox_inventory
ensure pma-voice
ensure sky_phone

add_ace resource.sky_phone command.add_ace allow
add_ace resource.sky_phone command.remove_ace allow

ensure oxmysql
ensure qb-core
ensure qb-inventory
ensure pma-voice
ensure sky_phone

Manual database installation

Hosts that require a manual schema import can run:

sky_phone/sql/install.sql

Keep runtime migrations enabled after the import because they install future schema upgrades.

First-start checklist

• The server console reports the selected framework and inventory without errors.
• An authorized administrator can open /phonepanel and save in SQL mode; an unprivileged player is denied.
• General shows the intended values after reopening the panel and restarting the resource.
• The configured phone item opens the phone.
• Unique phones receive a persistent IMEI and do not stack.
• A physical SIM provides cellular service, or automatic numbers work when SIMs are disabled.
• Calls have audio through the configured voice provider.
• Light and dark modes render correctly.
• The server-owned pepper values have been replaced and stored safely before production use.

Production setup guide

Review the following settings before opening a production server. In SQL mode, change them in the Configurator and save. Lua snippets below show field names and file-mode examples; do not replace complete configuration tables with these abbreviated examples.

Configuration files

Framework, inventory, and locale

Use General → Framework & integrations. In file mode, edit the existing Bridge fields:

Config.Bridge.Framework = "auto" -- auto, esx, qbox, qb
Config.Bridge.Inventory = "auto"
Config.Bridge.Locale = "en" -- 15 bundled locales, including en and de
Config.Bridge.Debug = false

Use explicit provider values when automatic detection could select the wrong resource. Debug mode adds diagnostic information; warnings and errors are always printed.

Choose a device mode

Config.Phone.Unique = true

With unique phones, using an item selects that exact handset. The F1 key reopens the last selected IMEI; when no handset has been selected, the server chooses the first concrete phone slot.

Choose a SIM mode

Config.Sim.Enabled = true

Test device- or SIM-mode changes on a database copy before applying them to an existing production server.

These are separate switches under General → Devices & SIM cards. Disabling physical SIMs does not prevent opening the phone and does not replace existing numbers. New number prefix and length values affect newly generated numbers only.

Configure calls and radio

Config.Calls.VoiceProvider = "pma" -- auto, yaca, pma, pma-voice, saltychat, salty
Config.Radio.VoiceProvider = "auto" -- auto, yaca, pma, saltychat

Start the selected voice resource before Free Phone. Radio's automatic selection checks YACA, PMA Voice, and SaltyChat. Configure restricted frequencies in Config.Radio.LockedChannels and display-name permissions in Config.Radio.DisplayName.AllowedJobs.

Configure media

In SQL mode, enter FiveManage and GIPHY keys in the Media detail section and save. In file mode, edit the server-only media file and restart:

Config.Media.FiveManage.ApiKey = "your-fivemanage-v3-media-token"
Config.Media.GiphyApiKey = "your-giphy-api-key"

Without a valid FiveManage token, Camera uploads, video uploads, Voice Memo uploads, and FiveManage Gallery imports are unavailable. Limit Gallery import origins through Config.Media.Import.Websites; direct URLs are accepted only from configured HTTPS hosts.

Configure server-owned music

Place MP3 or OGG files anywhere below config/music/. Optional artwork can use WEBP, PNG, JPG, or JPEG. Define stable tracks in Config.Music.Tracks:

Config.Music.Tracks = {
    {
        Id = "night-drive",
        Title = "Night Drive",
        Artist = "Sky Records",
    },
}

Name files after the track ID, for example night-drive.ogg and night-drive.webp. Restart sky_phone after adding tracks.

Set production security values

On a new production server, use Phone configurator → Server to replace all four defaults with long, random, different values before players create passcodes or social accounts:

Config.Server = {
    PasscodePepper = "replace-with-a-long-random-value",
    CrewLinkPasswordPepper = "replace-with-a-separate-random-value",
    FlipTokPasswordPepper = "replace-with-another-random-value",
    PicstagramPasswordPepper = "replace-with-a-third-random-value",
}

Players must treat Sky Cloud and social-app credentials as in-character roleplay credentials and must never reuse real-world passwords.

Configure optional apps

• Select a Garage provider in Config.Garage.System.
• Select a Housing provider in Config.Housing.System.
• Define company jobs, profiles, services, phone numbers, permissions, and availability under Config.Companies.Definitions.
• Configure Weazel News editorial jobs and grades under Config.WeazelNews.AllowedJobs.
• Add trusted external CrewLink ping resources to Config.CrewLink.ExternalPingResources.
• Configure custom-app origins, storage ceilings, rate limits, and adapters under Config.CustomApps.

Disable development tools

Before production, review:

Config.Phone.DevelopmentCommand = false
Config.TestData.Enabled = false
Config.Bridge.Debug = false

Inventory compatibility

These checks describe the adapters shipped with Phone 1.1.0. Finish the selected inventory's framework installation, choose its adapter in Phonepanel, save with the checkmark and restart after changing it. In SQL configuration mode, editing Part 2 of config.lua does not change the active inventory settings.

Unique phones and physical SIMs require individual item metadata and separate slots. Leave initial identities empty: Phone assigns IMEIs, SIM identities and numbers. Keep normal inventory use enabled and let Phone remove a SIM after a successful insertion. Do not add another use callback or automatic consumption.

ox_inventory

Phone listens for the server-side ox_inventory:usedItem event introduced in ox_inventory 2.38.0. An older version can close the inventory without reaching Phone's server handler. For forks, verify that the completed-use event still exists.

Search the complete inventory resource for Item('phone' and Item("phone", including modules/items/client.lua or the older items/client.lua. Remove this NPWD handler if present:

Item('phone', function(data, slot)
    local success, result = pcall(function()
        return exports.npwd:isPhoneVisible()
    end)

    if success then
        exports.npwd:setPhoneVisible(not result)
    end
end)

Keep the phone definition and Sky Phone client.export. The old handler can intercept use even when NPWD is stopped. Remove competing phone handlers, restart the server and recheck after inventory updates.

Core and MF

Phone 1.1.0's Core adapter expects a flat item list from getInventory and a slot for removeItemExact. Core's documented API uses a wrapper with content and an internal unique item ID for removal. An installation using that contract needs a matching adapter update; item definitions cannot fix it. On compatible versions, keep the sky_phone_devices category without a stack property and include all three names in Config.CloseAfterUse.

Merge this category into Core's existing configuration before adding the item definitions:

Config.ItemCategories["sky_phone_devices"] = {
    color = "#f2f2f2",
    takeSound = "take",
    putSound = "put",
}

The MF adapter requires ESX and the actual slot item as the fourth usable-callback argument. The older public MF examples use a different argument layout. Check the installed integration against the Phone MF adapter; unique = 1 cannot correct a callback mismatch.

SMX, HEX and native ESX

SMX stores one metadata record per character and configured item name. Multiple copies cannot represent independent phone identities through this bridge. Use Phone.Unique = false and Sim.Enabled = false, or choose an inventory with per-item metadata for transferable devices and physical SIMs.

HEX and native ESX provide count-based items. Phone automatically disables unique phones and physical SIMs for both adapters. Register the phone item only; adding SIM rows or unique flags does not enable physical SIM support.

Provider-specific setup

PS and JPR require QBCore in Phone's adapters. The codem adapter targets mInventory Remake (codem-inventory), not CodeM Supreme V2. Jaksam item entries must be persisted in its item file or editor; remove imported ox-only use hooks. One uses its persistent /inventory:manage editor, since runtime item-definition exports do not survive an inventory restart.

Test phone use, SIM insertion, transfers, stored identities and images with the installed provider before distributing the items. Optional metadata tooltips and SIM removal use the Phone exports.

Migrate from LB Phone

Free Phone detects supported LB Phone tables but never starts an import automatically.

skyphone:migrate lb-phone dry

skyphone:migrate lb-phone

Update safely

1. Back up the database, including the Configurator and Webhooks SQL settings.
2. Back up file-owned configuration, custom tones, music and other assets.
3. Preserve all four production pepper values.
4. Replace the resource files.
5. Preserve Part 1. In SQL mode keep the saved Configurator row; file edits do not import into it. In file mode merge configuration options instead of overwriting the new config blindly.
6. Add both Phone resource ACE grants and verify administrator membership when updating from the old framework-role checks.
7. Restart Free Phone, review warnings/errors, then verify admin access, General settings, phone/SIM item use and player hotkeys.