SolarOS 4.6.8 manual · app

Playground

playground is the catalog browser for community Python and Lua applications. It downloads one catalog from the configured repository and presents its categories as a foldable tree. Applications are scripts and assets, not firmware packages.

Start the browser:

playground
playground search QUERY...
playground install APP-ID [auto|flash|sd]
playground run APP-ID [ARG...]
playground delete
playground reload
playground refresh
playground storage [flash|sd]

Opening the TUI loads the saved local catalog without accessing the network. Press r in the tree, or run playground refresh, to download and save the current catalog. Run playground reload to explicitly reload the saved copy. Press / to search names, descriptions, authors, tags, and categories.

playground delete recursively deletes the catalog and every installed Playground application from the configured storage target, then clears the loaded catalog from memory. It retains the configured source and storage preferences. It also removes the legacy hidden .solar/playground directory when present.

The same operations are available directly from the shell. search prints matching catalog IDs, runtimes, names, and installation markers. install downloads and verifies one ID to the configured filesystem, or to an explicit flash or sd target. The omitted and auto targets both use the persistent Playground storage setting. run resolves the installed entry in the shell and launches its Python or Lua runtime directly; it does not create a Playground session. Additional arguments after the application ID are passed to Python through sys.argv or to Lua through arg. For example:

playground run qr-share --file /notes/wifi.txt

--file PATH is the canonical optional convention for a Playground script's primary input file. After --file, Tab completes filesystem paths. This also works through a multi-token alias such as run playground run.

After the catalog is loaded, Tab completes installed application IDs for both install and run without keeping a second ID list in memory. These commands use the loaded local catalog.

Opening the Playground TUI never accesses the network automatically. It shows the catalog saved by the last successful refresh. Press r or run playground refresh when you explicitly want to download the current catalog.

Application markers:

[ ] is available but not installed.
[I] is installed at the catalog version.
[U] has an update available.
[!] cannot run on this board or firmware.

Select an application and press i to install or update it directly from the catalog tree. Press u to uninstall an installed application after confirmation. The same actions are available after pressing Enter or Right for details; r runs an installed copy.

The catalog and default application installations live on the persistent storage target. Without a saved preference, Playground selects SD when it is mounted and flash otherwise. Inspect or change the setting with:

playground storage
playground storage flash
playground storage sd

The saved catalog lives at:

<configured-filesystem>/playground/catalog.json
<configured-filesystem>/playground/catalog.source

Installed files live on the selected filesystem:

<filesystem>/playground/python/APP-ID/
<filesystem>/playground/lua/APP-ID/

SD installations take precedence when the same application also exists in flash. Changing the storage setting does not migrate an existing catalog or installed applications. Refresh the catalog after changing it. When sd is configured, the SD card must be mounted to load or refresh the catalog and to install applications.

Sources and safety

The default catalog is generated by github.com/nilseuropa/solar_os_playground. Use a compatible fork by setting either its GitHub repository URL or the URL of its generated dist/catalog.json:

playground source
playground source https://github.com/example/solar_os_playground
playground source https://example.invalid/path/dist/catalog.json
playground source reset

GitHub repository URLs resolve to main/dist/catalog.json. The chosen source is stored in NVS. Each archive is checked against the exact size and SHA-256 digest declared by the downloaded catalog before installation. Installation is staged and replaces the prior version only after extraction and entry-file validation.

Playground applications are not sandboxed. Once started, they have the normal permissions of the SolarOS Python or Lua runtime. Only use repositories and applications whose maintainers you trust.

Controls

Up/Down, Page Up/Page Down, Home/End: navigate.
Enter, Space, Left, Right: fold categories or open details.
/: search the current catalog.
r: refresh in the tree, or run from details.
i: install or update the selected application from the tree or details.
u: uninstall the selected application from the tree or details, after confirmation.
Esc: cancel or go back in nested views; exit from the catalog tree.
q or the app-exit key: exit.

Quick reference

Run playground to browse the configured catalog. Use / to search, Enter for details, i to install, u to uninstall, and r to run. Refresh with r in the tree or playground refresh; use playground reload to load the saved catalog without a network request. Use playground source [URL|reset] to inspect or change the catalog source, and playground storage [flash|sd] to choose persistent catalog and application storage. Packages are hash-checked but scripts are not sandboxed. Shell automation can use playground search QUERY, playground install ID [auto|flash|sd], playground run ID [ARG...], and playground delete.