Settings Reference

This page lists every key the native loader reads from or writes to settings.json, its default when absent, and what it does. The loader keeps all of its configuration in this one file.

File location

settings.json is in the Unbound folder inside the app’s documents directory. On iOS, open it in the Files app at On My iPhone -> <App Name> -> Unbound, as described on the iOS page. If the file doesn’t exist when the loader starts, the loader creates it with the contents {}.

Structure

The root of the file is an object of stores. Each store is a namespace. The loader reads only from the store named unbound. Each addon gets its own store, keyed by its id, so an addon’s storage can never collide with the loader’s keys. See storage for how addons use the same file. Inside a store, keys are dot-paths that map to nested objects. For example, loader.update.url is stored as:

settings.json

{
	"unbound": {
		"loader": {
			"update": {
				"url": "http://localhost:4040/unbound.bundle"
			}
		}
	}
}

The native loader and Unbound’s JavaScript settings share the unbound store. Keys the loader doesn’t recognise, such as staff-mode or toasts.*, belong to the client. They are documented with the features that use them.

Keys

All keys below are inside the unbound store.

boolean

default:"true"

Turns the whole loader on or off. When it is false, the loader logs Loader is disabled. Aborting. and hands the bundle load straight back to Discord. No plugins, themes, fonts, updater, or hot reload run.This is the only key that is on by default. It is also the main way to recover a broken app. See disabling the loader.

boolean

default:"false"

Evaluates the bundled DevTools script in the JavaScript runtime before the main bundle. This is what lets React DevTools attach. Leave it off unless you are actively debugging.

object

Controls where the JavaScript bundle is downloaded from and when it is refetched.

Show properties

string

The base URL the bundle is downloaded from.

If the value ends in .bundle or .js, it is used as a direct file URL.
Otherwise it is treated as a directory, and the filename is appended.

The downloaded file is saved next to settings.json as unbound.bundle or unbound.js, matching the URL’s extension. When the extension changes, the old file with the other extension is deleted.This value also sets the hot reload target. The loader opens its hot reload stream to this URL’s origin (scheme and host).

boolean

default:"false"

Skips ETag revalidation and redownloads the bundle on every launch. When this is off, the loader sends the stored ETag as an If-None-Match header and keeps the existing file if the server responds 304.

boolean

default:"false"

Opens a hot reload connection to the origin of loader.update.url. No connection is made if that key is empty or doesn’t parse into a URL with both a scheme and a host.

string

default:""

Set by the loader. Don’t edit it by hand. It stores the etag response header from the last successful bundle download, so the next launch can revalidate instead of redownloading. Deleting it forces one full download.

boolean

default:"false"

Turns on recovery mode. When it is on:

The loader skips swizzling semantic colors, so themes stop being applied.
The client starts addons with an empty no-op instance instead of evaluating their bundles.
Addon cards still appear in the UI, but you can’t interact with them.

The toolbox toggles this key and reloads the app. See Troubleshooting for how to use recovery mode.

object

default:"{}"

Maps a font state name to the name of the font that replaces it. The native font layer looks up each override in both your installed custom fonts and the system fonts. If an override’s font isn’t loaded, it logs an error and leaves that state unchanged.Unbound’s font settings normally manage this key for you. See theme types and the addon manifest for how fonts are declared.

Three toggles are not in settings.json at all. The toolbox’s own switches are stored in NSUserDefaults, so editing settings.json never changes them:

UnboundShakeGestureEnabled (default on) opens the toolbox on a shake
UnboundThreeFingerGestureEnabled (default on) opens the toolbox on a three finger long press
UnboundAppIconEnabled swaps the app icon, and is only offered on non-App Store and non-TestFlight installs

The two gesture toggles protect each other. Turning one off turns the other back on, so you can’t lock yourself out of the toolbox.NSUserDefaults also holds UnboundDevOverlayButtonRelativeX and UnboundDevOverlayButtonRelativeY. They save where you dragged the dev overlay button, as a fraction of the screen size.

External edits apply without a restart

You can edit settings.json from the Files app, over SSH, or with any other tool, and the new values take effect without restarting the app. The loader watches the file for changes and reloads it in place. On each change, the loader reparses the file and posts an internal change notification that the rest of the loader listens for.

Live reload updates the values the loader holds, but it doesn’t re-run work that already happened at startup. Keys read once during launch, such as loader.enabled and loader.devtools, still need an app restart to take effect.

Writes made from inside the app are debounced by 300ms before they are flushed to disk, so a burst of changes produces one write.

Corrupt files are backed up

If settings.json fails to parse, or parses into anything other than a JSON object, the loader doesn’t crash the app. Instead it:

Copies the file to settings.json.corrupt-<timestamp> in the same directory. <timestamp> is the Unix time in whole seconds.
Resets settings.json to {}.
Continues starting up.

settings.json.corrupt-1753488000

Your old configuration is still readable in that backup. At worst, a bad hand edit costs you a restart.

Disabling the loader

Set loader.enabled to false to turn Unbound off without uninstalling anything. The check runs before any plugin, theme, or bundle work, so the loader does nothing and you get a stock app.

settings.json

{
	"unbound": {
		"loader": {
			"enabled": false
		}
	}
}

Use this when a bad bundle or addon makes the app unusable and you can’t get far enough into the UI to fix it. If you only need to get addons out of the way, use recovery instead, which changes less. For the full list of flags you can combine here, see configuration.

Addons

Plugins

Themes

Icon Packs

Development

API Reference

Loader

Settings Reference

File location

Structure

Keys

External edits apply without a restart

Corrupt files are backed up

Disabling the loader

​File location

​Structure

​Keys

​External edits apply without a restart

​Corrupt files are backed up

​Disabling the loader

File location

Structure

Keys

External edits apply without a restart

Corrupt files are backed up

Disabling the loader