Apps

As a parent I could never find a way to sandbox websites. Screen Time and the rest treat the browser as one app — but the browser is where the learning happens, and where the distraction is. So Luminum started as website whitelisting, and I still think Single Website is its killer app. Everything below grew out of that.

Luminum ships with the catalogue below. Nothing is installed until you install it, and nothing reaches the menu that you did not put there. Every app is described by a short YAML file — a recipe — and each entry here can be unfolded to show the exact file the device reads.

Website

webbrowserconfigurable

Turn any single web page into an app. The browser opens full screen on one address of your choosing — no tabs, no address bar, no way out to the rest of the web.

You pick the address during setup; nothing else can be browsed
Opens in kiosk mode, filling the screen, with no browser controls at all
Can be installed several times over for several different sites
Give it a clear title (e.g. "Maths practice") so the menu stays readable

Links inside the page still work, so check where the site can lead before handing it over. No age rating is given here — it depends entirely on the site you choose.

Recipe website.yaml

title: Website
description: |
  **Turn any single web page into an app.** The browser opens full screen on
  one address of your choosing — no tabs, no address bar, no way out to the
  rest of the web.

  - You pick the address during setup; nothing else can be browsed
  - Opens in kiosk mode, filling the screen, with no browser controls at all
  - Can be installed several times over for several different sites
  - Give it a clear title (e.g. "Maths practice") so the menu stays readable

  Links inside the page still work, so check where the site can lead before
  handing it over. No age rating is given here — it depends entirely on the
  site you choose.
singleton: false
tags:
  - web
  - browser
  - configurable
dependencies:
  apt:
    - chromium
variables:
  WEBSITE:
    type: string
    title: Website address
    description: Enter website that should be launched by browser app
    required: true
type: gui
script: |
  /usr/bin/chromium --noerrdialogs --password-store=basic --kiosk --window-position=0,0 --window-size=$RESOLUTION $WEBSITE

Downloads

Ages 3+filesmediautility

Open files that were downloaded to this device. A plain file browser locked to the Downloads folder, showing only the kinds of files you allow.

You choose the permitted file types at setup time (e.g. pdf,mp4,jpg)
Documents, videos and pictures all open full screen with a single keypress
Nothing outside the Downloads folder can be reached, and nothing can be executed
Files of other types are not even listed

Handy for handing over a video, a worksheet or a photo without opening up a whole file manager.

Recipe downloads.yaml

title: Downloads
description: |
  **Open files that were downloaded to this device.** A plain file browser
  locked to the Downloads folder, showing only the kinds of files you allow.

  - You choose the permitted file types at setup time (e.g. `pdf,mp4,jpg`)
  - Documents, videos and pictures all open full screen with a single keypress
  - Nothing outside the Downloads folder can be reached, and nothing can be executed
  - Files of other types are not even listed

  Handy for handing over a video, a worksheet or a photo without opening up a
  whole file manager.
ageFrom: 3
tags:
  - files
  - media
  - utility
dependencies:
  apt:
    - mupdf
    - vlc
    - feh
variables:
  EXTENSIONS:
    type: string
    title: Allowed extensions
    description: Comma-separated list of file extensions the user can open (e.g. pdf,mp4,jpg,png,txt)
    required: true
type: files
path: $LUMINUM_USER_HOME/Downloads
launchers:
  pdf:
    mode: gui
    script: /usr/bin/mupdf "$FILEPATH"
  mp4:
    mode: gui
    script: /usr/bin/vlc --fullscreen "$FILEPATH"
  webm:
    mode: gui
    script: /usr/bin/vlc --fullscreen "$FILEPATH"
  mkv:
    mode: gui
    script: /usr/bin/vlc --fullscreen "$FILEPATH"
  jpg:
    mode: gui
    script: /usr/bin/feh --fullscreen "$FILEPATH"
  jpeg:
    mode: gui
    script: /usr/bin/feh --fullscreen "$FILEPATH"
  png:
    mode: gui
    script: /usr/bin/feh --fullscreen "$FILEPATH"
  gif:
    mode: gui
    script: /usr/bin/feh --fullscreen "$FILEPATH"
  txt:
    mode: console
    script: /usr/bin/less "$FILEPATH"
  md:
    mode: console
    script: /usr/bin/less "$FILEPATH"

Library

Ages 6+readingbooksoffline

A bookshelf that works without the internet. Browse and read the books kept in the device's shared library folder — no shop, no account, no signal required.

Comes with three public-domain classics so the shelf is never empty
Peter Pan, Huckleberry Finn and an illustrated picture book to start with
Books open full screen in a distraction-free reader
Add your own books by dropping them into the shared library folder
The shelf is shared, so every app and profile sees the same books

Recipe library.yaml

title: Library
description: |
  **A bookshelf that works without the internet.** Browse and read the books
  kept in the device's shared library folder — no shop, no account, no signal
  required.

  - Comes with three public-domain classics so the shelf is never empty
  - *Peter Pan*, *Huckleberry Finn* and an illustrated picture book to start with
  - Books open full screen in a distraction-free reader
  - Add your own books by dropping them into the shared `library` folder
  - The shelf is shared, so every app and profile sees the same books
ageFrom: 6
tags:
  - reading
  - books
  - offline
dependencies:
  apt:
    - mupdf
    - arianna
  file:
    - url: https://library.luminum.tech/book/peter-pan.epub
      path: $LUMINUM_SHARED/library
      rename: peter-pan.epub
    - url: https://library.luminum.tech/book/huckleberry-finn.epub
      path: $LUMINUM_SHARED/library
      rename: huckleberry-finn.epub
    - url: https://library.luminum.tech/book/mr-zumbo.pdf
      path: $LUMINUM_SHARED/library
      rename: mr-zumbo.pdf
type: files
extensions:
  - pdf
  - epub
path: $LUMINUM_SHARED/library
launchers:
  pdf:
    mode: gui
    script: /usr/bin/mupdf "$FILEPATH"
  epub:
    mode: gui
    script: /usr/bin/arianna "$FILEPATH"

Code the Classics

Ages 9+codingpythongamesoffline

Learn to code real games in Python. Installs the full source code of the games from the Raspberry Pi Press book Code the Classics Vol. 1, together with the Thonny editor and everything needed to run them.

Complete, playable remakes of arcade classics — Pong, Bubble Bobble, Sokoban and more
Opens in Thonny with the project folder already listed on the side
Games run straight from the editor with F5, so every change is instantly visible
Built on Pygame Zero inside a private virtualenv — nothing to install or configure

Best used with the book at hand. A good next step once Scratch starts to feel small.

Recipe code-classics.yaml

title: Code the Classics
description: |
  **Learn to code real games in Python.** Installs the full source code of the
  games from the Raspberry Pi Press book *Code the Classics Vol. 1*, together
  with the Thonny editor and everything needed to run them.

  - Complete, playable remakes of arcade classics — Pong, Bubble Bobble, Sokoban and more
  - Opens in Thonny with the project folder already listed on the side
  - Games run straight from the editor with **F5**, so every change is instantly visible
  - Built on Pygame Zero inside a private virtualenv — nothing to install or configure

  Best used with the book at hand. A good next step once Scratch starts to feel small.
ageFrom: 9
tags:
  - coding
  - python
  - games
  - offline
dependencies:
  apt:
    - thonny
  git:
    url: https://github.com/raspberrypipress/Code-the-Classics-Vol1
    path: $LUMINUM_USER_HOME/code
  venv:
    path: $LUMINUM_USER_HOME/code/Code-the-Classics-Vol1/.venv
    requirements:
      - pgzero
configs:
  - path: $LUMINUM_USER_HOME/code/Code-the-Classics-Vol1/.thonny/configuration.ini
    mode: create
    data: |
      [general]
      ui_mode = regular
      [view]
      FilesView.visible = True
      [run]
      backend_name = LocalCPython
      working_directory = $LUMINUM_USER_HOME/code/Code-the-Classics-Vol1
      [LocalCPython]
      executable = $LUMINUM_USER_HOME/code/Code-the-Classics-Vol1/.venv/bin/python3
type: gui
maximize: true
script: |
  export THONNY_USER_DIR=$LUMINUM_USER_HOME/code/Code-the-Classics-Vol1/.thonny
  cd $LUMINUM_USER_HOME/code/Code-the-Classics-Vol1 && /usr/bin/thonny

Python Shell

Ages 10+codingpythonterminaloffline

The Python prompt, straight up. Opens an interactive Python session in the terminal — the quickest possible way to try an idea out.

Starts instantly, no desktop and no project setup needed
Perfect for arithmetic, playing with text and first experiments with loops
Every line is answered immediately, which makes mistakes cheap and obvious
Leave with exit() or Ctrl+D to come back to the menu

There is no editor here — for writing longer programs use Code the Classics.

Recipe python-shell.yaml

title: Python Shell
description: |
  **The Python prompt, straight up.** Opens an interactive Python session in
  the terminal — the quickest possible way to try an idea out.

  - Starts instantly, no desktop and no project setup needed
  - Perfect for arithmetic, playing with text and first experiments with loops
  - Every line is answered immediately, which makes mistakes cheap and obvious
  - Leave with `exit()` or **Ctrl+D** to come back to the menu

  There is no editor here — for writing longer programs use *Code the Classics*.
ageFrom: 10
tags:
  - coding
  - python
  - terminal
  - offline
dependencies:
  apt:
    - python3
type: console
script: python3

Scratch Desktop

Ages 6+codingcreativityscratchoffline

Scratch, installed right on the machine. The same colourful blocks, sprites and sounds as the Scratch website, but with no login and no internet connection needed.

Build animations, games and stories by dragging blocks together
Works completely offline, so a bad connection never interrupts a project
Noticeably faster on a Raspberry Pi than the browser version
Projects are saved as files on the device instead of to an online account
Opens full screen with nothing else reachable around it

Choose this over Scratch Online unless online sharing is wanted.

Recipe scratch-desktop.yaml

title: Scratch Desktop
description: |
  **Scratch, installed right on the machine.** The same colourful blocks,
  sprites and sounds as the Scratch website, but with no login and no internet
  connection needed.

  - Build animations, games and stories by dragging blocks together
  - Works completely offline, so a bad connection never interrupts a project
  - Noticeably faster on a Raspberry Pi than the browser version
  - Projects are saved as files on the device instead of to an online account
  - Opens full screen with nothing else reachable around it

  Choose this over *Scratch Online* unless online sharing is wanted.
ageFrom: 6
tags:
  - coding
  - creativity
  - scratch
  - offline
dependencies:
  apt:
    - scratch3
type: gui
maximize: true
script: |
  scratch-desktop

Scratch Online

Ages 6+codingcreativityscratchonline

Code with blocks at scratch.mit.edu. Opens the official Scratch website in a locked-down full-screen browser where nothing but Scratch can be reached.

Drag-and-drop blocks make animations, games and stories without any typing
The full online community: tutorials, studios and remixing other kids' projects
Projects are saved to a Scratch account, so they follow the child to any device
Needs a Scratch account to save work, and a steady internet connection

For a version that works offline and starts faster, install Scratch Desktop.

Recipe scratch-online.yaml

parent: website
title: Scratch Online
singleton: true
description: |
  **Code with blocks at scratch.mit.edu.** Opens the official Scratch website
  in a locked-down full-screen browser where nothing but Scratch can be reached.

  - Drag-and-drop blocks make animations, games and stories without any typing
  - The full online community: tutorials, studios and remixing other kids' projects
  - Projects are saved to a Scratch account, so they follow the child to any device
  - Needs a Scratch account to save work, and a steady internet connection

  For a version that works offline and starts faster, install *Scratch Desktop*.
ageFrom: 6
tags:
  - coding
  - creativity
  - scratch
  - online
parameters:
  WEBSITE: https://scratch.mit.edu

The same catalogue on the device. Each entry explains what the app is for, what it needs, and — where it matters — the age it suits.

Writing your own

Anything not in the catalogue you add yourself, and it takes one file. Start from the reference, or copy whichever recipe above is closest to what you want and change it.

Make a folder for it in the shared apps folder, /home/luminum/apps/. The folder name is the app's internal name, so /home/luminum/apps/maths-practice/ for a new app called that. Admin mode → Launch GUI gives you a desktop with a shortcut to the shared folder.
Save the recipe as recipe.yaml inside it — so /home/luminum/apps/maths-practice/recipe.yaml. The title in the file is what appears on the menu, not the folder name.
Choose it from the menu. It is on the menu as soon as the file is there. The first time it is picked, Luminum asks for the admin password and installs it before running, so you can write a recipe and let the install happen when it is first needed.

The cheapest useful recipe is a copy of Website with a different address — that is exactly how Scratch Online is built:

parent: website
title: Maths Practice
parameters:
  WEBSITE: https://example.org/maths
ageFrom: 8
tags:
  - maths
  - online