# nm-applet

NetworkManager's tray applet on the workstations, as a module (novox/hq ADR 0208). It requires
`x11-display`, so it is assigned only where a display server is held on the same machine.

## Owns

| what | where |
|---|---|
| the applet (and, as its dependencies, the connection editor and libnma) | package `network-manager-applet`, from the official repositories |

Nothing else. It holds no seat, makes no contribution and writes no file.

- **No AUR.** Both workstations run the official package (`extra`), installed explicitly.
- **NetworkManager is not this module's.** The `networkmanager` module holds the node's uplink
  (`node-uplink`) with it, on servers as well as workstations. It declares the `networkmanager`
  package, its one drop-in and its service. This module declares none of them (ADR 0210 §4: one
  package, one module), and it does not declare the applet's own dependencies (`nm-connection-editor`,
  `libnma`) either: the package brings them.
- **Why a module of its own, and not a part of `networkmanager`:** that module runs on machines with no
  display, where a tray applet has nothing to draw on and the package would pull in GTK. The applet is
  a desktop piece, beside `blueman` (for `bluetooth`) in the same way.
- **The connections stay the operator's.** The applet is NetworkManager's secret agent: it asks for a
  network's password and can keep it in the keyring. Profiles, networks, secrets and addresses are
  joined at the machine (the `networkmanager` module's README). The tools never ask for them.
- **The applet's settings are found.** It keeps its switches in dconf (`org.gnome.nm-applet`): the
  notifications it shows and whether it shows itself. The module neither sets nor resets them.

## How it starts: the package's autostart entry, and nothing else

The package ships `/etc/xdg/autostart/nm-applet.desktop` (`nm-applet`, `NotShowIn=KDE;GNOME;`). The
session runs it once at login through the `i3` module's `dex --autostart --environment i3`. **That
entry is the applet's one start.** The module adds no `xinitrc` slot and no `node-display-session`
exec, because either would start it a second time.

- **Excluded:** the window manager's `exec … nm-applet`, which the `i3` module's configuration dropped.

## Tools

They are served by the node's runtime as the operator account (ADR 0175).

| tool | does |
|---|---|
| `nm_applet_status` (r) | <ul><li>whether the applet runs: pid, since, and the scope or unit it runs in</li><li>the installed version, and what starts it at login</li><li>its switches in `org.gnome.nm-applet`</li><li>NetworkManager's overall state: state, connectivity, Wi-Fi and networking on or off. Never a connection, a network, a secret or an address</li></ul> |
| `nm_applet_restart` (a) | asks the applet to end (SIGTERM), forces it after 5 s, and starts `nm-applet` in the operator's session as a transient user unit `mesh-nm-applet`, so it outlives the tools runtime. NetworkManager and its connections are not touched; for those few seconds no secret agent answers a password prompt. Refused plainly when nobody is logged in to the desktop |
| `nm_applet_check` (r) | <ul><li>the package is installed</li><li>exactly one start: the package's entry is present and not hidden by an entry of the account, and `dex` is installed</li><li>no window-manager exec</li><li>one applet runs in a desktop session</li><li>`NetworkManager.service` is active</li></ul>Each finding says what to do |

The tools find the session's `DISPLAY` and `XAUTHORITY` from the window manager's own environment, as
`blueman` does. Every command has a timeout and capped output. Everything runs through an injected
runner and a fake root in the tests.

## What changes when it is assigned

| | laptop | desktop |
|---|---|---|
| package | none: `network-manager-applet` 1.36.0, explicit, from `extra` | the same |
| start | none: dex starts the applet from the package's entry, in the login session's scope | none on disk. **The applet running now came from the predecessor's window-manager line** (`nm-applet --sm-disable`, a child of i3, since the session of 2026-10-04 16:00). That session began before the `i3` module dropped the line and installed `dex`, so the next login is the first that starts it from the entry |

## Migration (ADR 0182)

Nothing is required on either machine. On the desktop, log out and in once, or run
`nm_applet_restart`, and the applet runs from its one start. `nm_applet_check` then answers `ok`.

## Leaves as found

- The applet's dconf settings (`/org/gnome/nm-applet/`).
- `/etc/xdg/autostart/nm-applet.desktop`, the package's own file.
- Every connection profile and secret.

## Relies on

- **The `networkmanager` module, for NetworkManager.** There is no dependency mechanism between two
  modules that hold no seat, so nothing refuses `nm-applet` without it; `nm_applet_check` reports it.
  `networkmanager` holds `node-uplink`, but a module cannot depend on a seat without a resource or a
  contribution that derives it (ADR 0207, ADR 0210 §3). **Assign both.**
- **`i3`'s `dex` line for the start**, which is equally undeclared: XDG autostart has no seat.
  Assigned without `i3`, the applet is installed and does not start. `nm_applet_check` says so.
- A display server on the same machine (`x11-display`, ADR 0208 §3).