mesh-catalog/modules/jetbrains-toolbox

jetbrains-toolbox

JetBrains Toolbox on the workstations, as a module (novox/hq ADR 0208). Toolbox installs, updates and launches the JetBrains IDEs. It requires x11-display, so it is assigned only where a display server is held on the same machine.

Owns

Nothing on disk. It holds no seat, makes no contribution and writes no file. What it owns is the rule that Toolbox has one start, and the tools that see Toolbox and its IDEs.

• Not a package. The distribution does not package Toolbox. JetBrains ships a tarball, which the operator unpacked once. Toolbox keeps itself in ~/.local/share/JetBrains/Toolbox:

  • its launcher and runtime, in bin/;
  • the IDEs, in apps/;
  • its settings, state and update channels, in .settings.json, state.json and channels/;
  • its account, in accounts.json and .securestorage;
  • its logs.

• Kept as found, not a pinned archive (ADR 0205). ADR 0205 ships software the distribution lacks as a pinned archive of the module's own. Toolbox is the exception it does not foresee:

  • it updates itself in place, and it updates the IDEs. A pinned copy would be a second writer of bin/: either the push rolls Toolbox back after every self-update, or Toolbox overwrites the mesh's copy;
  • its licence is JetBrains', not one the mesh's store may redistribute.

  So the module installs nothing. The operator installs Toolbox once, by its own instructions (Install-linux-tar.txt beside the launcher), and Toolbox keeps itself current. toolbox_check says when it is missing.

• Toolbox's files are found (ADR 0182). The module never declares, writes or removes any of them. The tools read the version, the switches, the tool list and the channels. They never read the account, the secure storage or the logs.

How it starts: Toolbox's own autostart entry, and nothing else

One process has one starter (the rule picom states for the desktop modules). Toolbox's starter is its own XDG autostart entry, ~/.config/autostart/jetbrains-toolbox.desktop (…/bin/jetbrains-toolbox --minimize).

• Toolbox writes that entry while its setting Launch Toolbox App at system startup is on, and removes it when the setting is off. The setting is autostart in .settings.json; absent means on, Toolbox's default.
• The session runs every XDG autostart entry once at login: the i3 module's dex --autostart --environment i3.

Why not a contribution to node-display-session: Toolbox would still write its own entry whenever the setting is on, and the session would start it twice. The module cannot own the entry either: Toolbox rewrites it, and that would be two writers. So, as nextcloud-client does, the module adds no start, and toolbox_check holds the rule:

• the entry exists exactly when the setting says so;
• no window-manager exec starts Toolbox as well.

Off is an answer, not a fault. With the setting off, Toolbox does not start at login and runs when the operator opens it (from the launcher, or a jetbrains:// link). toolbox_check notes that and finds nothing wrong.

Tools

They are served by the node's runtime as the operator account (ADR 0175), and are read-only except restart. No answer carries the JetBrains account: neither its id nor anything from accounts.json or .securestorage. Paths under the home are answered as ~/….

tool	does
toolbox_status (r)	whether Toolbox is installed, its version (bin/build.txt) and the version its state was last written by whether it runs: pid, since, and the unit or scope what starts it at login its switches: launch at login (and whether that is the default), update the tools automatically, the shell scripts' folder, the theme, how many versions it keeps for a rollback every tool it installed: name, version, build, update channel (Release, Early Access Program …), whether that tool updates itself, where it is and whether it is on disk any directory under apps/ that its list does not name
toolbox_restart (a)	ends Toolbox (SIGTERM, forced after 8 s) and starts …/bin/jetbrains-toolbox --minimize in the operator's session. The start is a transient user unit mesh-jetbrains-toolbox, so it outlives the tools runtime. The IDEs Toolbox launched are their own processes and keep running. Answers the pids. Refused plainly when nobody is logged in to the desktop, or when Toolbox is not installed
toolbox_check (r)	Toolbox is installed at most one start: the entry is there exactly when the setting is on, it runs Toolbox, dex is installed, and no window-manager exec at most one Toolbox runs, and one runs when it starts at login every tool in its list is on disk Each finding says what to do. Notes cover the setting being off, and directories it does not list

Which process is Toolbox: the kernel keeps 15 characters of a process's name, so Toolbox's comm is jetbrains-toolb. A process with that comm counts only when its command is Toolbox's launcher. The bundle is named toolbox-tools, not jetbrains-toolbox-tools. The longer name cuts to the same comm, and toolbox_restart would have ended the tools themselves.

The tools find the session's DISPLAY and XAUTHORITY from the window manager's own environment, as the other desktop modules do. 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

	g14	shanks
Toolbox	none: Toolbox 2.8.1.52155 in ~/.local/share/JetBrains/Toolbox (tarball install), not running. Its files are from 2025-09-04, the last time it ran, so it has not updated itself or the IDEs since	none: Toolbox 3.2.0.65851, the same place (.installation-type says APP), last run 2026-02-23; not running
start	none: Launch at startup is off (autostart: false) and there is no entry, so nothing starts it at login. toolbox_check: ok, with a note	none on disk: the setting is at its default (on), and Toolbox's own entry (--minimize) is there. The i3 module's dex starts it at the next login. The session running now (since 2026-10-04) began before dex was installed, which is why Toolbox does not run. toolbox_check names that until toolbox_restart or the next login
IDEs	Fleet 1.48.261, PyCharm 2025.2.1.1, Rider 2025.2.0.1, WebStorm 2025.2.2: all on the Early Access Program channel	RustRover 2026.1 EAP and Fleet 1.48.261 on Early Access Program; PyCharm 2025.3.2.1, Rider 2025.3.2 and WebStorm 2025.3.2 on Release
updates	update the tools automatically: on	the same; one version kept for a rollback

The two machines differ in Toolbox's major version and in the IDEs' channels. Both are the operator's choices in Toolbox, and the module reports them rather than aligning them.

Migration (ADR 0182)

Nothing is required on either machine. The module removes nothing and adds no start.

• shanks: run toolbox_restart, or log out and in, and Toolbox runs from its one start. toolbox_check then answers ok. Toolbox wrote its entry with the executable bit set (0744), which systemd's autostart generator warns about at every login. That is harmless under i3, and the entry is Toolbox's, so the module leaves it.
• g14: nothing. To have Toolbox start at login there too, open it and tick Launch Toolbox App at system startup. It writes its own entry, and it then updates itself and the IDEs, which it has not done since 2025-09.
• Not the module's: ~/.profile on g14 adds Toolbox's scripts/ folder to PATH by hand. The account's environment is node-environment's holder's. If the IDE launch scripts are wanted on PATH on both machines, that is a contribution to it, not a line in ~/.profile.

Leaves as found

• ~/.local/share/JetBrains/Toolbox/, entirely: the launcher, the runtime, the IDEs, the settings, the state, the account, the logs, and the link Toolbox itself keeps in scripts/ for Fleet.
• ~/.config/autostart/jetbrains-toolbox.desktop, Toolbox's own.
• The desktop entries Toolbox writes for itself and each IDE in ~/.local/share/applications/. Those include jetbrainsd.desktop on shanks.
• The x-scheme-handler/jetbrains default, which is the xdg module's.

Relies on

• i3's dex line for the start. Nothing in the mesh says so yet: XDG autostart has no seat, and a module without a seat or contribution has no way to depend on another module. Assigned without i3, Toolbox is not started at login. toolbox_check says so when its setting is on.
• A display server on the same machine (x11-display, ADR 0208 §3).