Using Plugins

Experimental — under heavy development

The plugin system is under heavy development and subject to breaking changes at any time. Treat it as experimental — use it for tinkering, not in a setup you depend on. Community plugin submissions are not accepted yet.

Plugins extend Noctalia with bar widgets, desktop widgets, control-center shortcuts, launcher providers, and headless background services — all driven by trusted Luau scripts running in isolated VMs. A plugin is a directory containing a static plugin.toml manifest and one or more .luau entry scripts.

Plugins come from sources. Two git sources ship by default:

• official — https://github.com/noctalia-dev/official-plugins
• community — https://github.com/noctalia-dev/community-plugins

You can also add your own git repos or local directories.

Enabling a plugin

Nothing is active until you enable it — installed ≠ enabled. Enabling a plugin from a git source exports just that plugin’s directory from the source repo cache into $XDG_STATE_HOME/noctalia/plugins/materialized/. Noctalia owns both the repo cache and exported runtime files.

From the settings GUI

Open Settings → Plugins. Use Add source to add a git repo or local directory. Each configured source is listed with Update where applicable and Remove for custom sources, and every discovered plugin has an enable toggle. Toggle a plugin on to fetch + activate it; toggle off to deactivate it. Incompatible plugins (see Compatibility) are shown but cannot be enabled.

Plugins that expose plugin-level settings show a gear on their row — open it to configure options shared across all of the plugin’s parts (for example the screen recorder’s codec, quality, and output folder). Settings persist to the state dir, so a read-only config directory is fine. Bar-widget entries can also declare widget settings, edited where that widget is configured.

If a plugin is enabled in config.toml and you disable it in Settings, Noctalia writes an app-owned [plugins].enabled override to settings.toml. That override wins until you remove or edit it.

From the command line

noctalia msg plugins list                              # every plugin across all sources, with enabled state
noctalia msg plugins enable noctalia/screen_recorder   # fetch (if needed) + enable
noctalia msg plugins disable noctalia/screen_recorder  # disable; code + settings are retained
noctalia msg plugins update official                   # update a source, then hot-reload its plugins

Manage sources too:

noctalia msg plugins source list
noctalia msg plugins source add my-repo git https://github.com/me/my-plugins
noctalia msg plugins source add my-dev path ~/dev/my-plugins
noctalia msg plugins source remove my-repo

The built-in official and community sources can be updated and have their Update on startup toggle changed in Settings, but are protected from removal in Settings and IPC. Custom git/path sources are removable.

Enabling a plugin makes its entries available. Its bar widget then shows up in the Add-widget picker — add a widget instance just like any built-in widget (or configure one by hand with type = "<author>/<plugin>:<entry>"). A control-center shortcut is added from the control-center shortcuts settings, like any other shortcut.

Configuration

Plugin state lives under [plugins]. The enabled list and the sources are user intent (declarative-friendly); the app also writes runtime toggles to its state file, and both are merged.

[plugins]
# Fully-qualified ids ("<author>/<plugin>") that are active.
enabled = ["noctalia/screen_recorder"]

# A git source: cached and updated by Noctalia.
[[plugins.source]]
name        = "official"
kind        = "git"
location    = "https://github.com/noctalia-dev/official-plugins"
auto_update = false   # opt-in background pull on startup (off by default)

# A path source: an immutable local directory Noctalia treats read-only
# (no git ops). Ideal for local development or Nix-managed plugins.
[[plugins.source]]
name     = "my-dev"
kind     = "path"
location = "~/dev/my-plugins"

Plugins placed by hand under ~/.local/share/noctalia/plugins/<plugin>/ are discovered as a built-in local source — handy for development. Like every plugin, they must be enabled before they activate. See File locations for where plugin code and everything else lives.

Git source operations are non-interactive. Private repos must be reachable through an already-working credential helper, SSH agent, or SSH config; otherwise clone/update fails and Noctalia continues without prompting for a password. Git source runtime files are exported caches, not editable plugin state. Use a path source or ~/.local/share/noctalia/plugins/ for local plugin development.

A source name is its identity. Replacing a git source with the same name but a different location deletes Noctalia’s app-managed repo cache and exported runtime files for that source, then re-fetches from the new location when needed.

Updating

noctalia msg plugins update <source> updates the source and hot-reloads its enabled plugins. Git sources can opt into auto_update for a background update on startup. Updates are safe per enabled plugin: if one enabled plugin’s new version requires a newer Noctalia, Noctalia keeps that plugin’s previous exported copy, still updates compatible enabled plugins from the same source, and advances the source catalog. After Noctalia is updated, the held plugin can catch up from the already-updated source revision.

Compatibility

Every plugin declares a mandatory min_noctalia in its manifest. A plugin requiring a newer Noctalia than you run is shown but badged “requires newer Noctalia” and cannot be enabled.

Writing your own

Want to build a plugin? See Plugin Development.