FreedomBox Customization

Though FreedomBox's philosophy is to have the user make as few decisions as possible about the FreedomBox itself, a few options for customization have been provided to facilitate some advanced use cases.

Change Default App

Available since version: 0.36.0
Skill level: Basic

Use Case: A FreedomBox that primarily runs only one public-facing application whose web application is set as the landing page when someone visits the domain name of the FreedomBox over the internet.
e.g. A university using MediaWiki running on FreedomBox as a course wiki wants its students typing in the domain name into their browser to directly go to the wiki bypassing the FreedomBox home page.

Configuration: Change the Default App in the configure page to whichever app you want to be served as default.

Custom Shortcuts

Available since version: 0.40.0
Skill level: Advanced

Use Case: The administrator of a community deployment of FreedomBox manually installs a few additional unsupported applications on the FreedomBox and wants users to be able to transparently access them through the web and mobile applications of FreedomBox.

Note: This feature is meant to be used with applications that are end-user facing, i.e have a web or mobile client.


Create a file called custom-shortcuts.json in Plinth's configuration directory /etc/plinth and add additional shortcuts in JSON format. The file should have follow the same JSON schema as the Plinth API. You can refer to the JSON schema by visiting https://<my-freedombox-url>/plinth/api/1/shortcuts.

An example file adding one additional shortcut for NextCloud.

   1 {
   2     "shortcuts": [{
   3         "name": "NextCloud",
   4         "short_description": "File Hosting Service",
   5         "description": ["Nextcloud is a suite of client-server software for creating and using file hosting services."],
   6         "icon_url": "/plinth/custom/static/themes/default/icons/nextcloud.png",
   7         "clients": [{
   8             "name": "nextcloud",
   9             "platforms": [{
  10                 "type": "web",
  11                 "url": "/nextcloud"
  12             }]
  13         }]
  14     }]
  15 }

The corresponding icons for the shortcuts listed in the above file should be placed in the directory /var/www/plinth/custom/static/themes/default/icons/. The file names of the icons should match with those provided in /etc/plinth/custom-shortcuts.json.

After adding an entry for NextCloud in custom-shortcuts.json and an icon, restart Plinth by executing the command  systemctl restart plinth  on the FreedomBox. You can also restart the FreedomBox from the web interface.

After restart the Plinth home page will display an additional shortcut for NextCloud as shown below:
NextCloud custom shortcut on the Plinth home page

The same shortcut will also be displayed in any Android apps connected to the FreedomBox.

NextCloud custom shortcut in the Android app








Live Help

Where To Start








To Do








FreedomBox for Communities

FreedomBox Developer Manual

HELP & DISCUSSIONS: Discussion Forum - Mailing List - #freedombox | CONTACT Foundation | JOIN Project

Next call: Saturday, April 11th at 14:00 UTC

Latest news: Announcing Pioneer FreedomBox Kits - 2019-03-26

This page is copyright its contributors and is licensed under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.