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.

Install the resource

sky_phone/config/config.lua
sky_phone/config/media.lua

Config.Bridge = {
    Framework = "auto",
    Inventory = "auto",
    Locale = "en",
    Debug = false,
}

Config.Phone = {
    Item = "phone",
    Unique = true,
    Keybind = "F1",
    AllowMovement = true,
}

Config.Sim.Enabled = true

Config.Phone.Unique = true
Config.Bridge.Inventory = "ox"

["phone"] = {
    label = "Phone",
    weight = 190,
    stack = false,
    consume = 0
},

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)

Config.Phone.Unique = true
Config.Bridge.Inventory = "qb"

phone = {
    name = 'phone',
    label = 'Phone',
    weight = 190,
    type = 'item',
    image = 'phone.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'Free Phone'
},

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

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.
• 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. Restart sky_phone after changing Lua configuration.

Configuration files

Framework, inventory, and locale

Config.Bridge = {
    Framework = "auto", -- auto, esx, qbox, qb
    Inventory = "auto", -- auto, ox, qb, lj, qs, codem, core, mf, smx
    Locale = "en",      -- en or de
    CallbackTimeout = 15000,
    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.

Configure calls and radio

Config.Calls.VoiceProvider = "pma" -- 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

Add the FiveManage V3 Media API token to the server-loaded media file:

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 Free Phone after adding tracks; no frontend rebuild is required.

Set production security values

Replace all three bundled values before players create passcodes or social accounts:

Config.Server = {
    PasscodePepper = "replace-with-a-long-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

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.
2. Back up config/config.lua, config/media.lua, and custom music or media.
3. Preserve all three production pepper values.
4. Replace the resource files.
5. Merge new configuration options instead of overwriting the new config blindly.
6. Restart Free Phone and review all warnings and errors.