Installing Mods

A mod is a piece of the Browserland desktop — a taskbar chip, an app window, a Control Panel setting — and a broker can be handed a new one at runtime, without a restart. This page covers installing, uninstalling and managing mods from the Control Panel. For what a mod actually is, how one is written, and the trust it takes on, see Writing a Mod.

Where to find it

Open Control Panel → Mods on the broker's own tab (the broker this page is being served from — installing and uninstalling always act on that one broker, not a remote host you've added). The pane lists every mod that broker knows about, each with an enable checkbox, its provenance, and its live status.

Installing a mod

Click Install a mod… and pick a mod's folder (or a single .js file) from your computer. Before anything is sent, you get an install preview — the exact files and manifest that will be uploaded, plus any advisory warnings (a missing field, a file over the size limit, and the like) so you can back out before committing to something the broker would reject anyway.

If the broker's operator has configured an admin token, installing and uninstalling ask for it in a dialog titled Admin token required. The page password is not enough. Type the token and press Continue; it is held in memory until you reload the page and is never saved or synced, so a reload asks again. If the token was wrong, the broker refuses with admin_required and the dialog reappears. The dialog is part of the page, and every installed mod runs in that page, even one you have unchecked, so a hostile installed mod can read the admin token as you type it. Type it only when you trust every mod installed on that broker; otherwise make the request from outside the page, as the Mods section of Technical-Reference shows.

If no admin token is set, the Mods pane says so at the top: then any page or mod holding the broker's password can install and uninstall mods there.

Uninstalling a mod

Every installed mod's row carries an Uninstall button. Shipped mods have no Uninstall button at all — they are part of the broker's own program and can't be removed this way; only a mod installed at runtime can be. Uninstalling gives you the option to also delete the mod's data stored on that broker (its /mod-store value and its pin); without it, only the mod's code is removed, and that data stays on the broker, where a later install of a mod with the same id picks it up. Data a mod keeps in other browsers is never touched.

Reload to finish

An install or uninstall does not take effect in the page you're looking at. Every mod's script shares one execution scope with every other mod and with the desktop's own code, and JavaScript cannot re-declare or un-declare something already loaded — re-running a mod's script in the same page throws an error instead of updating it. So the broker takes the change immediately (the next browser to load its page sees it), but this tab needs a reload to pick it up. If you just installed something and it doesn't seem to be there yet, that's why — reload the page.

Provenance: shipped or installed

Each row in the Mods pane carries a small shipped / installed badge. Shipped mods came in the broker's own program and were there before you touched anything. Installed mods arrived through this install feature — from you, or from whoever administers that broker. The badge is how you tell the two apart at a glance.

?nomods=1 — the rescue hatch

If an installed mod bricks the desktop — throws on load, breaks a shared piece of the page — you might not be able to reach the Control Panel to remove it. Add ?nomods=1 to the broker's URL by hand and reload: the desktop comes up with no mods fetched or run at all, shipped or installed, so you can get back into the Control Panel and sort things out. It's a one-time, read-only flag — nothing is saved, so leave it off the URL once you're done and mods load normally again.

Installed but disabled is not contained

Unchecking a mod in the Mods pane stops it from running — but its code is still present in the page, still fetched, and its stylesheet is still live either way. Disabling is a way to turn a mod off, not a way to keep code you don't trust off your machine. Only uninstalling removes it.

A mod is not sandboxed

Nothing above is a security boundary. A mod runs with the same authority as the rest of the desktop — it can read tokens, reach every broker route the UI itself uses, and touch the same page state as core. Installing a mod is a trust decision, the same as installing any other program: only install one you'd be willing to review. See Writing a Mod for the full picture.

Mods that ship off by default

A handful of shipped mods start disabled and have to be switched on yourself, under Control Panel → Mods:

Mod	Why it's off by default
Clipboard	Clipboard history can carry secrets, so nothing is captured until you opt in
AI status	Checking providers' status pages exposes the broker's egress IP to those hosts
Update check	It makes the broker contact GitHub; ticking it on yourself is your consent for the serving broker to check for updates and to apply one and restart itself, for each of those gates its config does not already own (a config key can pin any gate either way)
Terminal font	An opt-in setting rather than something everyone needs on
Git status	It runs git in every terminal's working directory on a slow poll, so it stays off until you opt in

Turning one on is the same as enabling any other mod — tick its checkbox in the Mods pane.