Configuration basics

The configuration file is a simple INI socket.ini file in the root of the project. The file is read on startup and the values are used to configure the project. Sometimes it's useful to overide the values in socket.ini or keep some of the values local (e.g. [ios] simulator_device) or secret (e.g. [ios] codesign_identity, [ios] provisioning_profile, etc.) This can be done by creating a file called .ssrc in the root of the project. It is possible to override both Command Line Interface (CLI) and Configuration File (INI) options.



; other settings


headless = false

; other settings



platform = ios ; override the `ssc build --platform` CLI option

[settings.ios] ; override the `[ios]` section in `socket.ini`

codesign_identity = "iPhone Developer: John Doe (XXXXXXXXXX)"
distribution_method = "ad-hoc"
provisioning_profile = "johndoe.mobileprovision"
simulator_device = "iPhone 15"

Note that "~" alias won't expand to the home directory in any of the configuration files. Use the full path instead.


Key Default Value Description
copy "src" ssc will copy everything in this directory to the build output directory. This is useful when you want to avoid bundling or want to use tools like vite, webpack, rollup, etc. to build your project and then copy output to the Socket bundle resources directory.
env An list of environment variables, separated by commas.
flags Advanced Compiler Settings (ie C++ compiler -02, -03, etc).
headless false If true, the window will never be displayed.
name The name of the program and executable to be output. Can't contain spaces or special characters. Required field.
output "build" The binary output path. It's recommended to add this path to .gitignore.
script The build script. It runs before the [build] copy phase.


Key Default Value Description
forward_arguments false If true, it will pass build arguments to the build script. WARNING: this could be deprecated in the future.

Key Default Value Description
sources[] Configure your project to watch for sources that could change when running ssc. Could be a string or an array of strings


Key Default Value Description
root "/" Make root open index.html
default_index "" Set default 'index.html' path to open for implicit routes
watch false Tell the webview to watch for changes in its resources

Key Default Value Description
reload true Configure webview to reload when a file changes


Key Default Value Description


Key Default Value Description
allow_fullscreen true Allow/Disallow fullscreen in application
allow_microphone true Allow/Disallow microphone in application
allow_camera true Allow/Disallow camera in application
allow_user_media true Allow/Disallow user media (microphone + camera) in application
allow_geolocation true Allow/Disallow geolocation in application
allow_notifications true Allow/Disallow notifications in application
allow_sensors true Allow/Disallow sensors in application
allow_clipboard true Allow/Disallow clipboard in application
allow_bluetooth true Allow/Disallow bluetooth in application
allow_data_access true Allow/Disallow data access in application
allow_airplay true Allow/Disallow AirPlay access in application (macOS/iOS) only


Key Default Value Description
flags Advanced Compiler Settings for debug purposes (ie C++ compiler -g, etc).


Key Default Value Description
bundle_identifier A unique ID that identifies the bundle (used by all app stores). It's required when [meta] type is not "extension". It should be in a reverse DNS notation
copyright A string that gets used in the about dialog and package meta info.
description A short description of the app.
file_limit Set the limit of files that can be opened by your process.
lang Localization
maintainer A String used in the about dialog and meta info.
title The title of the app used in metadata files. This is NOT a window title. Can contain spaces and special characters. Defaults to name in a [build] section.
type "" Builds an extension when set to "extension".
version A string that indicates the version of the application. It should be a semver triple like 1.2.3. Defaults to 1.0.0.


Key Default Value Description
icon The icon to use for identifying your app on Android.
aapt_no_compress Extensions of files that will not be stored compressed in the APK.
enable_standard_ndk_build Enables gradle based ndk build rather than using external native build (standard ndk is the old slow way)
main_activity Name of the MainActivity class. Could be overwritten by custom native code.
manifest_permissions Which permissions does your application need:
native_abis To restrict the set of ABIs that your application supports, set them here.
native_cflags Used for adding custom source files and related compiler attributes.


Key Default Value Description
codesign_identity signing guide:
distribution_method Describes how Xcode should export the archive. Available options: app-store, package, ad-hoc, enterprise, development, and developer-id.
provisioning_profile A path to the provisioning profile used for signing iOS app.
simulator_device which device to target when building for the simulator


Key Default Value Description
categories Helps to make your app searchable in Linux desktop environments.
cmd The command to execute to spawn the "back-end" process.
icon The icon to use for identifying your app in Linux desktop environments.


Key Default Value Description
category A category in the App Store
cmd The command to execute to spawn the "back-end" process.
icon The icon to use for identifying your app on MacOS.
codesign_identity TODO Signing guide:
codesign_paths Additional paths to codesign


Key Default Value Description
files Files that should be added to the compile step.
headers Extra Headers


Key Default Value Description
cmd The command to execute to spawn the “back-end” process.
icon The icon to use for identifying your app on Windows.
logo The icon to use for identifying your app on Windows.
pfx A relative path to the pfx file used for signing.


Key Default Value Description
height The initial height of the first window.
width The initial width of the first window.


Key Default Value Description
runner The headless runner command. It is used when no OS specific runner is set.
runner_flags The headless runner command flags. It is used when no OS specific runner is set.
runner_android The headless runner command for Android
runner_android_flags The headless runner command flags for Android
runner_ios The headless runner command for iOS
runner_ios_flags The headless runner command flags for iOS
runner_linux The headless runner command for Linux
runner_linux_flags The headless runner command flags for Linux
runner_mac The headless runner command for MacOS
runner_mac_flags The headless runner command flags for MacOS
runner_win32 The headless runner command for Windows
runner_win32_flags The headless runner command flags for Windows