Plugin API reference

What it is

This is the full reference for WolOS shell plugins: the plugin.toml manifest, every section it can contain, the permissions, the Lua API and the wol plugin commands. The Plugins page has the short version.

Why

One document for the whole API means an agent or a person can write a working plugin from this page alone. Every TOML and Lua block below is parsed and run by WolOS's own tests.

How

1. Find ready-made plugins in the Store under Plugins: each row says what it does and what it asks for, with Get, Turn On or Update.

   

2. To write your own, start with wol plugin new <id> (or Create Plugin in the Store, which opens Plugin Maker), edit, then wol plugin check <id> until it passes.
3. See it with wol plugin run, which shows what it draws, and wol plugin enable to put it on your desktop. It gets only the permissions its manifest lists.

If something goes wrong

Related

Plugin Maker · The Store · Privacy and permissions · The plugins page

Reference

Decision: ADR 0031. Code: crates/shared/src/plugins.rs (manifest contract, parse, the schema), crates/shared/src/layout.rs (bar and Dock slots plugin items land in), crates/wol-lua/src/plugin.rs (Lua API v1 in the widget sandbox), crates/core/src/plugins.rs (folders, check, grants, state, toggles, failure counter, scaffold, pack), crates/controller/src/plugin.rs (wol plugin). Reference plugin: plugins/shell/org.wolos.stats/. Schema: docs/plugins/plugin.schema.json, installed at /usr/share/wolos/plugins.schema.json.

This is the one document for the whole plugin API. Every TOML and Lua block in it is parsed and run by crates/controller/tests/plugin_docs.rs, so what you read here is what the code accepts.

What a plugin is

A plugin is a folder named after its id with a plugin.toml and the files it names. Nothing else: no install hooks, no binaries, no symlinks, at most 1 MiB. The shell looks in ~/.local/share/wolos/plugins/<id>/ (yours, reloaded when it changes) and /usr/share/wolos/plugins/<id>/ (shipped or installed through wopkg). A plugin may contribute, through sections of its manifest: a menu bar item, a Dock entry, a desktop card, a panel, search results, a Control Center tile, a toggle, a hotkey, a web app, a theme, a Looks preset and compositor window rules. Code is Lua, run in the sandbox of ADR 0020 (wol-lua: 16 MiB, 5 million instructions per load, render or click, no io, os, require, debug, loaders or bytecode). A plugin cannot leave the HIG: it returns Kit view trees and the shell draws them. It reaches the system only through the calls below and, for anything that changes the system, through wol verbs, which pass the helper policy and the audit log under the plugin's id (Settings > Assistants & Automation).

Ids are reverse-DNS (org.example.stats) or <user>.<name> (alice.stats): lowercase labels of letters, digits and -, joined by dots. org.wolos.* is reserved for plugins WolOS ships.

The manifest, plugin.toml (schema 1)

schema = 1
id = "alice.stats"
name = "Stats"
version = "1.0"
author = "Alice"
license = "MIT"
description = "CPU and memory in the menu bar, with a desktop card."
min_wolos = "0.12"
permissions = ["run"]

[[menubar]]
id = "bar"
script = "bar.lua"
side = "right"

[[widget]]
id = "card"
script = "card.lua"
sizes = ["small", "medium"]

[[hotkey]]
id = "top"
default = "super+shift+t"
exec = ["foot", "-e", "btop"]
group = "Stats"

Header keys, in this order:

Then one [[section]] per contribution. Every entry has an id (1 to 32 lowercase letters, digits, -, _), unique across the whole plugin; the shell refers to it as <plugin id>/<entry id>. Unknown keys and unknown sections are load errors, each a sentence naming the place ([[menubar]] 1: unknown key "colour"; it takes id, script, side.). Files are relative paths inside the folder, no .., no hidden names.

icon is a symbolic icon name or a .png/.svg in the folder.

The rules a [[hypr]] section will be held to (windowrule or layerrule, value effect [args], match, ...; shared::plugins::check_hypr, already run by check):

• windowrule effects allowed (placement and looks): float, tile, pseudo, size, minsize, maxsize, move, center, workspace, rounding, bordersize, animation, opacity, idleinhibit. Effects that take windows away from the person (nofocus, noinitialfocus, fullscreen, maximize, pin, stayfocused, suppressevent, dimaround, nodim and anything else not listed) are refused.
• layerrule effects allowed (the plugin's own surfaces): blur, blurpopups, ignorezero, ignorealpha, animation. Not xray, noanim or dimaround.
• opacity may not go below 0.5 (HYPR_MIN_OPACITY): from 0.5 to 1.
• Every rule needs at least one match that names something, like class:^(org.example.App)$; a match every window passes (.*, class:.*, title:^(.+)$) is refused.

A plugin with everything:

schema = 1
id = "alice.everything"
name = "Everything"
version = "0.3"
license = "GPL-2.0-or-later"
permissions = ["notifications", "run", "http", "clipboard", "open", "toggles"]

[[menubar]]
id = "bar"
script = "bar.lua"

[[dock]]
id = "launch"
name = "Terminal"
icon = "utilities-terminal-symbolic"
exec = ["foot"]

[[widget]]
id = "card"
script = "card.lua"

[[panel]]
id = "sheet"
script = "sheet.lua"
anchor = "centre"

[[search]]
id = "calc"
script = "calc.lua"
kind = "command"
prefix = "="

[[toggle]]
id = "awake"
on = ["wol", "power", "awake", "on"]
off = ["wol", "power", "awake", "off"]

[[tile]]
id = "awake-tile"
icon = "weather-clear-symbolic"
label = "Stay Awake"
toggle = "awake"

[[hotkey]]
id = "sheet-key"
default = "super+shift+e"
exec = ["wol", "shell", "show", "control-center"]

[[webapp]]
id = "mail"
name = "Mail"
url = "https://mail.example.com/"
icon = "mail-unread-symbolic"
profile = "own"

[[theme]]
id = "night"
file = "night.json"

A plugin without code: a Control Center tile bound to a toggle, and a theme.

schema = 1
id = "alice.quiet"
name = "Quiet"
version = "1.0"
license = "MIT"
description = "A Silence tile and a dark theme."

[[toggle]]
id = "silence"
on = ["wol", "focus", "on"]
off = ["wol", "focus", "off"]

[[tile]]
id = "silence-tile"
icon = "notifications-disabled-symbolic"
label = "Silence"
toggle = "silence"

[[theme]]
id = "night"
file = "night.json"

The TOML subset: key = value lines, "strings" with \" \\ \n \t \uXXXX, 'literal strings', whole numbers, true/false, [lists] (may span lines, trailing comma allowed), [[sections]] and # comments. Dotted keys, inline tables, multi-line strings, floats and dates are refused with a sentence.

Permissions

Declared in the header, shown before the plugin is turned on (wol plugin enable; in the Store, the "Asks to:" line of the plugin's row, which wopkg checks against the package's own manifest before it installs anything: a list entry that names other permissions than the signed package is refused), stored per plugin in $XDG_CONFIG_HOME/wolos/plugins.json and revocable in Settings. A plugin that is on but whose newer manifest asks for more shows "needs a new grant" in wol plugin list until it is enabled again; in the Store its row says what is new ("Asks for more now: ...") with an Allow button that runs the same wol plugin enable, so an update never leaves a permission silently refused. Without the permission the call does not exist (wol.run == nil), so a script can test for it.

wol.run { "wol", ... } runs the wol verb as a helper named after the plugin: the helper policy, on-screen approval and the audit log apply exactly as for an AI assistant (docs/modules/automation.md). Other programs run as you, with the limits of widget sources (own process group, CPU limit, nice 10, output cap, never a shell). The argv of [[toggle]], [[dock]] and [[hotkey]] entries are commands too: one whose first word is not wol is refused by check unless the plugin declares run, and the shell runs, shows or binds it only while run is granted. wol plugin check and wol plugin enable list each such command. wol.http_get needs a grant for each host; the first use shows the consent sentence ("Allow this plugin to read data from api.example.com.") and the card asks. A read follows no redirect: a host that answers with one (to another site, the local network or this machine) gives an error, never the other body. wol.notify posts at most 10 notifications a minute per script (the rest answer false, message); titles are cut at 120 characters and bodies at 1000. No new privilege path exists: a plugin that needs more is a libwol app (ADR 0020).

Lua API v1

A script is one file that ends with return wol.<kind> { ... } matching its section. Loading a script never acts: the service calls are added after the file has run, so only render, popover, query and handlers reach them. Every service call returns ok, message (or value, message) instead of raising.

Scripts

refresh: seconds between renders, 0 to 86400 (default 60; 0 = only after input). After a handler runs, the shell renders again.

-- bar.lua: CPU and memory from `wol sys stats --json` (permission "run").
local cpu, mem, err = 0, 0, nil
local function read()
  local ok, out = wol.run { "wol", "sys", "stats", "--json", timeout = 5 }
  if not ok then err = out; return end
  local v, e = wol.json.decode(out)
  if not v then err = e; return end
  err = nil
  cpu = math.floor((v.cpu_percent or 0) + 0.5)
  local total, used = (v.memory and v.memory.total) or 0, (v.memory and v.memory.used) or 0
  mem = total > 0 and math.floor(used * 100 / total + 0.5) or 0
end
return wol.menubar {
  refresh = 5,
  render = function()
    read()
    if err then return wol.label { "Stats: -" } end
    return wol.row { spacing = 8, wol.label { "CPU " .. cpu .. "%" }, wol.label { "MEM " .. mem .. "%" } }
  end,
  popover = function()
    return wol.stack { spacing = 8,
      wol.label { "Stats", role = "title" },
      wol.label { err or ("CPU " .. cpu .. "%, memory " .. mem .. "%"), role = "secondary" },
      wol.button { label = "Open Top", on_click = function() wol.run { "foot", "-e", "btop" } end },
    }
  end,
}

Parts (the view tree)

Limits (shared::view): 12 levels deep, 200 parts, text up to 1024 bytes. Interactive parts are numbered in tree order in the printed JSON; wol plugin run ... <n> clicks part n.

-- sheet.lua: every part once (a panel).
local on, level, name = true, 40, ""
return wol.panel {
  title = "Everything",
  render = function()
    return wol.stack { spacing = 12,
      wol.row { spacing = 8, wol.image { "emblem-default-symbolic", size = 32 }, wol.label { "Everything", role = "title" }, wol.spacer(),
        wol.button { label = "Close", on_click = function() end } },
      wol.list {
        wol.item { title = "First", subtitle = "A row", icon = "folder-symbolic" },
        wol.item { title = "Second", button = { label = "Open", on_click = function() wol.show("control-center") end } },
      },
      wol.toggle { label = "Enabled", on = on, on_change = function(v) on = v end },
      wol.slider { value = level, min = 0, max = 100, on_change = function(v) level = v end },
      wol.text_field { text = name, placeholder = "Your name", on_change = function(t) name = t end },
      wol.label { "Caption", role = "caption" },
    }
  end,
}

Services

Always present:

With a permission:

-- card.lua: state, JSON and the web (permissions "http" and "notifications").
-- Loading never acts: wol.state and the other services exist from the first render on.
local n, quote
return wol.widget {
  refresh = 900,
  render = function()
    n = n or wol.state.get("count") or 0
    quote = quote or wol.state.get("quote")
    local body, e = wol.http_get("https://api.example.com/quote")
    if body then
      local v = wol.json.decode(body)
      if v and v.text then quote = v.text; wol.state.set("quote", quote) end
    end
    return wol.stack { spacing = 8,
      wol.label { quote or e or "...", role = "title" },
      wol.row { spacing = 8,
        wol.label { "Seen " .. n .. " times", role = "secondary" },
        wol.spacer(),
        wol.button { label = "+1", on_click = function()
          n = n + 1
          wol.state.set("count", n)
          if n == 10 then wol.notify("Ten!", "You looked ten times.") end
        end },
      },
    }
  end,
}

-- calc.lua: a command search ("=2+2"). The script gets the text after the prefix.
return wol.search {
  query = function(text)
    local expr = text:gsub("[^%d%+%-%*/%.%(%) ]", "")
    if expr == "" then return {} end
    return {
      { title = expr, subtitle = "Copy result", icon = "accessories-calculator-symbolic",
        on_activate = function() wol.state.set("last", expr) end },
    }
  end,
}

Failure and limits

A render or click that errors shows the sentence on the card or bar item, not a crash. Three failures in a row turn the plugin off with a toast saying why (wol_core::plugins::Health). A script that runs too long is stopped ("This widget took too long and was stopped."), as is one that uses too much memory.

"Too long" has two bounds (crates/wol-lua/src/lib.rs, Deadlines, INSTRUCTION_BUDGET): 5 million Lua instructions, and a wall-clock deadline per call, 200 ms to load the file, 50 ms per render or popover, 200 ms per click, change or query (the host may set others; the shell uses these, because scripts run on its drawing thread). The clock is read every 250 instructions and before every library call whose time grows with its input (string.rep, find, match, gmatch, gsub, upper, lower, reverse, sub, format, byte, char, pack, unpack, table.move, concat, insert, remove, sort, unpack, utf8.*), so a loop around such a call stops at the deadline even inside pcall. Those calls are also capped one by one: string.rep at 2^20 repeats and 1 MiB of result (an empty string repeated 2^40 times is refused), table.move and table.concat at 2^20 items, table.insert/remove at 2^20 items and table.sort at 2^16 (lengths read through __len, as Lua's C code reads them), pattern subjects at 1 MiB. A script stopped for time stays stopped: every later render, click or query answers the same sentence without running it, until the file changes and is loaded again. To wol_core::plugins::Health that answer is a failure like any other, so a host that counts failures turns a stopped plugin off after three.

wol plugin

--json on any command gives machine-readable output; without a TTY it is the default.

How an AI agent writes and tests a plugin in 5 steps

1. wol plugin new alice.weather menubar,widget makes a folder that already passes check. Read /usr/share/wolos/plugins.schema.json (the manifest schema) and this page.
2. Edit plugin.toml (name, description, permissions, entries) and the .lua files. Keep scripts small: one read() that fetches data, one render() that returns parts.
3. wol plugin check alice.weather --json until "valid": true. Every problem is one sentence naming the file or [[section]] n and what to change.
4. wol plugin run alice.weather menubar --json prints the view tree; wol plugin run alice.weather widget card 1 --json clicks part 1 first and shows the new tree and the events the handler caused. Use XDG_STATE_HOME=$(mktemp -d) for a clean state and WOL_PLUGIN_HOSTS=api.example.com when the plugin reads the web.
5. wol plugin enable alice.weather to see it on the desktop; wol plugin pack alice.weather to make the .wolplug to share.

Distribution

Three ways in, all user level, none waiting for an OS release (ADR 0031): drop the folder in ~/.local/share/wolos/plugins/; wol plugin add <folder|.wolplug> (stage, check, move; hooks never run); or the signed plugin index through the Store's Plugins page, which also offers updates. The Store installs only what the index lists and signs (a download that is not signed, or does not match its entry, is refused; there is no unsigned path and no confirmation for it there). Unsigned plugins (a folder, or a .wolplug the index did not sign) are marked unreviewed, like community-collection packages, and need --yes on wol plugin add; a .wolplug file has no double-click handler, so a downloaded package is added from a terminal. A plugin that needs a newer WolOS than the running one (min_wolos) is listed as "Needs WolOS x" and not offered; an installed one keeps working and keeps its switch while the newer version waits. Plugin updates are found in the background: the desktop checks the plugin list about once an hour (the verified cache; a download only when the cache is missing, expired or stale, and only when a plugin is installed) and shows one notification per new version, not only when the Store page is open. Planned, not in 0.12: wol plugin add by index id or git URL, and wopkg update updating plugins.

.wolplug (frozen): a zstd-compressed ustar archive with the members <id>/<file> for every file of the folder, then SHA256 (BSD sha256 lines, one per file, sorted, ADR 0011 form), then optionally SHA256.sig (the raw 64-byte Ed25519 signature of the SHA256 bytes, by the index key in /usr/share/wolos/keys/). wol plugin pack writes it unsigned; the index CI adds the signature. File paths inside are at most 99 characters.

Where things live