QUICK TIPS: Configuration


Hi All,

Today I wanted to show you how to configure OS.js and its features. I’ve seen that many people change the core files to modify behaviour, which in many cases is not necesarry.

You can modify the current things via configuration files:

  • Base
    • Handler (Authentication and connection handler)
    • MIME and filetype mappings
    • Build options and templates
    • Themes and package repositories
  • Client
    • Connection settings and base URI/URLs
    • Locales
    • Preloads (additions)
    • Autostart
    • Package Manager settings
    • Settings Manager pools
    • VFS Settings
    • Third-party API settings
    • Window Manager and Desktop Environment settings
  • Server
    • Directories and VFS
    • Group permissions
    • Proxies
    • HTTP options and modes

Configuration files

Configuration files are stored in src/conf. These files are all merged together to form one configuration object, hence the numbered prefix. This ensures they are loaded in the correct order.

The file 900-custom.json is generated by Grunt. See section below on how to use Grunt to configure OS.js.

By default Objects are merged together, but Arrays are overwritten (support for merging arrays will come soon).

Everything is namespaced and separated into sections. Look at the included files to get a better idea.

Basic configuration

You can use Grunt to modify simple configurations like strings and numbers. For example:

# Change {'client': {'Locale': <value>}}
grunt config --set=client.Locale --value="no_NO"

There are also some other special commands for managing certain sections: https://os.js.org/doc/manuals/man-build-grunt.html

Advanced configuration

For more advanced changes you have to create your own file (ex 910-something.json or use the 900-custom.json Grunt creates for you).


You can override the default settings of the Window Manager and Desktop Environment (CoreWM) which is located in src/packages/default/CoreWM/settings.js.

  "client" : {
    "WM" : {
      "args": {
        "defaults": {
          "theme": "customthemename",
          "enableIconView" : true

Updating changes

Just run grunt config to update both the client and server generated configuration files.

Make sure to restart your server if you made changes to the server settings!


When you have a chance, can you make the debug notice at the bottom right of the screen configurable too? Even better make fields available to us so that we can assemble them to make up the debug notice. Fields might include version, last modified, developer contact, etc.


Yes. I’ll add it to the list :slight_smile:


You can now make your own watermarks! :slight_smile:



I’ll expand it so you can use %HEAD% (for git), %DATE% (build date) later


Made it a bit better so you can add custom lines instead of the pre-defined ones: https://github.com/os-js/OS.js/blob/master/src/conf/110-client.json#L35


FYI: This information is no longer correct.

Please see: https://os.js.org/manual/configuration/


This is no longer relevant as of v2.1. Please see: https://manual.os-js.org/