Exponential Desktop reference
| Path | What |
|---|---|
~/.config/exponential-desktop/ui/<name>.json |
A shell document; yours wins over the factory copy. A git repository. |
~/.config/exponential-desktop/ui/theme.json |
The look, in the genUI theme format; extends may name a built-in theme. |
/usr/share/exponential-desktop/ui/ |
The factory documents. |
~/.config/exponential-desktop/compositor.toml |
Compositor settings: keyboard, windows, lock, idle, protected apps, outputs, theme bridge. A broken file is logged and ignored. |
A document name is lowercase letters, digits, - and _.
The document
Section titled “The document”A genUI document plus a surface header. Top-level keys: surface, exactly one of root (nested tree) or components (A2UI’s flat list), and optionally data, catalogId, $schema, $comment. Unknown keys are refused.
{ "surface": { "layer": "top", "anchor": ["top", "left", "right"], "size": { "height": 40 }, "exclusiveZone": 40, "functions": ["ede.focus", "ede.tray"] }, "root": { "id": "panel", "component": "Box", "children": [ { "id": "clock", "component": "Text", "props": { "text": { "path": "/time" } } } ] }}Layer surface
Section titled “Layer surface”| Key | Values | Default |
|---|---|---|
layer |
background, bottom, top, overlay |
top |
anchor |
edges from top, bottom, left, right, each once |
none (centred) |
size |
{width?, height?}, whole positive px; required on every axis not stretched between two opposite anchors |
|
exclusiveZone |
px kept clear along the anchored edge; needs an anchor | 0 |
margin |
{top, right, bottom, left} px, never negative |
0 |
keyboard |
none, on-demand, exclusive (top and overlay only) |
none |
onDemand |
true: opened by a hotkey or host function, never at start |
false |
functions |
the host functions this document may call | none |
Popup surface
Section titled “Popup surface”popup: {parent, anchor, placement, size}: a popup of the document parent, under its component anchor. placement is bottom-start (default), bottom-end, top-start, top-end, left-start or right-start. size with width and height is required. A popup carries no layer, anchor, exclusiveZone, margin, keyboard or onDemand; functions works as above.
One issue refuses the whole document; the last good version stays.
- No
Inputwithtype: password. - No
functionCalloutsidesurface.functions. - Every id once.
- Then every component, prop, style and token is checked against the catalog.
Data the shell feeds
Section titled “Data the shell feeds”| Path | What |
|---|---|
/time |
Local time. |
/windows |
The open windows. |
/apps, /query |
Installed desktop entries, filtered by what is typed. |
/switcher |
Open windows, most recent first, with live thumbnails. |
/osd |
The level the OSD shows. |
/notifications |
toasts (newest first), list (the session’s history), count. |
/tray, /traymenu |
Tray items; the open item’s menu rows. |
/services/<domain> |
A service snapshot. |
/outputs |
Displays: modes, scale, position. |
/config |
compositor.toml. |
/user |
The person. |
Host functions
Section titled “Host functions”| Function | Arguments |
|---|---|
ede.launch |
{command} |
ede.focus |
{window} |
ede.close |
{window} |
ede.select |
{window} (the switcher) |
ede.lock |
|
ede.logout |
|
ede.power |
{action: suspend | reboot | poweroff} |
ede.open_document |
{name} |
ede.close_document |
{name} |
ede.notify_close |
{id} |
ede.notify_action |
{id, key} |
ede.notify_clear |
|
ede.tray |
{service} |
ede.tray_menu |
{service, id} |
ede.service |
{domain, action, args} |
ede.output |
{name, mode?, scale?}, applied live and saved to [[outputs]] |
ede.config |
the compositor.toml sections to write (keyboard, theme), then a reload |
Services MCP
Section titled “Services MCP”exponential-services runs in the session. Its MCP server listens on loopback; each agent session gets its own bearer.
exponential-services list # the domainsexponential-services get sound # a snapshotexponential-services call sound set_volume '{"percent": 40}'exponential-services tools # the MCP tool listexponential-services grant <session> [label] [system,ui] # a bearer for an agent sessionTools: <domain>_get for every domain, <domain>_<action> for every action. A call outside the grant comes back as an isError result. Every call writes an audit row. A domain whose daemon is missing answers {available: false, reason}.
| Domain | Through | Actions | Capability |
|---|---|---|---|
network |
NetworkManager | wifi_enable {on}, connect {ssid, password?}, disconnect {device} |
system |
sound |
PipeWire (WirePlumber) | set_volume {percent}, mute {on}, set_mic_volume {percent}, mute_mic {on}, set_default {id} |
ui |
bluetooth |
BlueZ | power {on}, connect {device}, disconnect {device}, discover {on} |
system |
power |
UPower, power-profiles-daemon, logind | set_profile {profile}, suspend, hibernate, reboot, poweroff |
system |
disks |
udisks2 | mount {volume}, unmount {volume} |
system |
updates |
apt | refresh, upgrade |
system |
firmware |
fwupd | refresh |
system |
printers |
CUPS | ||
about |
the system |
exponential-ctl
Section titled “exponential-ctl”Drives the running compositor.
exponential-ctl windows # open windows, JSON linesexponential-ctl outputs # outputs, JSON linesexponential-ctl capture [--output NAME | --window ID] --png FILE [--expect-drawn]exponential-ctl key CODE [--pressed | --released] [--bindings] # an evdev key codeexponential-ctl pointer X Y [--click] [--bindings] # move, optionally left click--bindings sends the input as the person’s, so it reaches the desktop’s own keys (Alt+Tab, Super, the media keys). Protected windows are black in captures and refuse input.
exponential-ui
Section titled “exponential-ui”exponential-ui check # load the directory; what applies, what is refusedexponential-ui validate FILE... # validate without applyingexponential-ui set NAME FILE|- # validate, write NAME.json, commit (NAME = theme: theme.json)exponential-ui rm NAME # delete NAME.json as a commitexponential-ui discard NAME # drop NAME's uncommitted editexponential-ui undo # revert the newest editexponential-ui reset # every factory document backexponential-ui log [N] # the history, newest firstexponential-ui watch # one JSON change per lineexponential-ui digest FILE # the content digest the shell reports with a frameexponential-ui dir # the ui directory--dir DIR and --factory DIR go before the command.
exponential-sealed
Section titled “exponential-sealed”The Tier B surfaces, compiled in.
exponential-sealed lockexponential-sealed polkitexponential-sealed consent --title … --body … [--allow …] [--deny …] # prints allow or deny, exits 0 or 1exponential-sealed share| Keys | Action |
|---|---|
| Super | Menu |
| Alt+Tab | Switcher (Shift reverses) |
| Alt+` | Switcher over the focused app’s windows |
| Super+L | Lock |
| Super+Shift+E | Log out |
| Super+Shift+R | Factory documents back, restart the shell |
| Ctrl+Alt+T | Terminal |
Screenshot to ~/Pictures/Screenshots |
|
| Super+Left / Right / Up / Down | Tile left, right, maximize, restore |
| Super+1…9 | Workspace (with Shift: take the window along) |
| Alt+F4 | Close |