QuickTS

01

Overview

QuickTS adds one tile to Quick Settings. Clicking it brings the tailnet up or down — or starts a login, if the daemon is waiting for one — and its arrow opens everything else. It talks to tailscaled the way the tailscale command does, so there is nothing else to install.

02

Install

Requires

• GNOME Shell 50.
• Tailscale 1.82 or later — the first release whose /status says which peers can receive a file. Developed and checked against 1.102.
• Your user set as the Tailscale operator (below).

$ sudo tailscale set --operator=$USER

From a release

$ curl -LO https://github.com/Ghost-Assembly/quickts/releases/latest/download/[email protected]
$ gnome-extensions install --force [email protected]
$ gnome-extensions enable [email protected]

From a clone

$ just setup
$ just install
$ just enable

03

The menu

Top to bottom. Rows marked hidden appear only when they have something to show.

• Tailscale The tile. Its subtitle says what is going on: “via nas”, the tailnet’s name, “Connecting…”, “Waiting for approval”, “Not logged in” or “Off”.
• Problems Hidden when all is well. “Not permitted…” copies sudo tailscale set --operator=$USER; “Log in…” appears only when the backend needs a login.
• 2 warnings Hidden when healthy. The daemon’s own text, up to three and then “2 more”; a warning with a link opens it.
• Exit node: name None · Suggested: node, while none is chosen · the tailnet’s candidates · one row per Mullvad country, which opens its cities in place. Choosing the node in use clears it.
• Devices Choosing one opens its actions in place: Ping, which answers on the row (“0.8 ms, direct”, “42 ms, relayed via lhr”), Copy address, Copy DNS name and Send files….
• Send files Hidden when nothing can receive. Ineligible peers are listed grayed out with the daemon’s reason.
• 2 received files Hidden when empty. Saves into your download folder.
• Settings Accept routes · Accept DNS · Allow LAN access · Block incoming · Tailscale SSH · Run as exit node. Flipping one does not close the menu.
• Profiles Hidden when there is only one account.

Two icons appear in the top bar: the QuickTS icon while the tailnet is up, and a VPN icon while traffic leaves through an exit node. While the tailnet is starting or waiting for an admin’s approval the tile is on, so a click turns it off.

GNOME allows one open submenu at a time, so Exit node and Devices swap their own contents rather than opening a nested menu. Each offers a way back, and closing the menu returns both to their lists.

04

Preferences

Open them from the Extensions app, or with just prefs from a clone.

05

Keyboard

One shortcut opens Quick Settings with QuickTS expanded. It is unbound by default, so it cannot collide with a GNOME shortcut; choose one in the preferences window, which records the next key combination you press.

A bare key is not accepted: it would be taken from every application. Shift alone is accepted only with a key that types nothing and that editing text does not need, such as Shift+F5. Shift+A is how a capital A is typed, and Shift with an arrow key, Home, End, Page Up, Page Down, Tab, Enter or a dead key selects text, moves focus, ends a line or types an accented letter: the keys GNOME Settings refuses, plus dead keys. The shortcut does nothing on the lock screen or the login screen.

It is stored under quickts-open-menu. The prefix matters: Mutter keeps one table of keybinding names for the whole Shell and refuses a name that is already registered, so a plain open-menu could be lost to any extension that chose the same word.

06

Security

QuickTS talks to tailscaled over its local socket, with the same LocalAPI the tailscale command uses. Anything the menu can do, you could already do from a terminal as the operator; it grants no privilege you did not have.

• Request paths are built in one pure module, where node ids and file names are percent-encoded before they reach a URL.
• Sending streams files from disk to a peer the daemon lists in /file-targets at the moment of sending, whichever row the send started from.
• Receiving checks the sender’s file name before it becomes a path: one containing / or a NUL byte, or starting with ., is refused and left with the daemon. The file is created exclusively in your download folder — an existing file or a planted symlink is never overwritten or followed; the save moves on to name (1) — and streamed to disk, never held in the Shell’s memory.
• Tailnet data is text. Peer names, tags and health messages come from the coordination server and are never used to build a command or markup.
• Nothing identifying is logged. Peer names, addresses, keys and file names stay out of the journal; a failed send is reported in a notification, which GNOME does not log.

Report a vulnerability privately through GitHub’s advisory form; the security policy has the details.

07

Architecture

Every decision lives in a pure module that imports nothing from GNOME, so the suite tests them on plain Node. The files that touch gi:// or resource:/// only carry decisions out.

Every module

The diagram above shows the main ones. Every file under modules/, what it decides, and which other modules it imports — everything not listed here imports nothing of its own:

The bus is a signal, not a source

The IPN bus says that something changed; /status and /prefs say what. No value is ever read out of a notification: a peer on the bus and a peer in /status are different shapes, and two translations of one dataset cannot be kept in agreement. modules/bus.js offers no way to get a peer out, and a test pins its exports to keep it that way. While the menu is closed the re-read leaves out the peer map, most of the payload on a large tailnet.

After an outage the bus reports only what changes from then on, so the first message on a new connection triggers one full re-read of preferences, profiles and peers.

Cancellation settles the awaiter

One token per enable. Canceling it aborts every request, settles every pending wait and drops every GLib source — the last two in the same callback, deliberately. A timer removed without its awaiter settled leaves an await that never returns, keeping its whole call stack alive for the rest of the session.

The model is not a GObject

It is a plain observable: subscribe() returns its own disposer, and subscribers receive a whole snapshot plus a list of what moved. There are no properties to bind and no notify:: ordering to get wrong.

One shape for a peer

modules/peers.js is the only file that reads a raw peer field. Whether a node is the exit node comes from the preferences, so the tick follows the click rather than lagging the network, and a node shared in from another tailnet keeps enough of its name to stay distinguishable. Pure modules decide; modules/panel.js and its section modules choose the wording, so translators see whole sentences.

08

The LocalAPI

QuickTS tries /run/tailscale/tailscaled.sock, then /var/run/…, and looks again on each connection, so installing or starting Tailscale after you log in is picked up.

09

Testing

1. 01just test runs the unit suite on plain Node. GNOME imports resolve to recording stubs through Vitest’s aliases, and the fake daemon behaves like a Linux tailscaled: it honors the subscription mask and never sends a runtime netmap.
2. 02just localapi-check runs modules/io.js under plain gjs against the real daemon. A stub of libsoup can only prove the stub behaves; this is what notices Tailscale changing its JSON.
3. 03just test-live boots a headless gnome-shell and asserts that enable, disable and enable again leave no JavaScript error, orphaned source or lifetime warning, then checks the bundle and runs the LocalAPI check. It needs a real Shell and a running tailscaled.
4. 04just test-docs checks this site in Chromium and Firefox: accessibility in both color schemes, a 360px phone, no scripts and no request to another origin.

Fixtures are written from the observed schema rather than captured. A real response carries node keys, addresses, the tailnet name and an account email, and this repository is public.

10

Packaging

just build makes the zip with plain zip, because gnome-extensions ships inside the gnome-shell package and CI has no GNOME. scripts/pack-check.sh keeps the official tool as the authority, diffs the two listings and confirms every shipped icon decodes — an icon that fails to load is silent.

The zip holds metadata.json, extension.js, prefs.js, modules/, schemas/ and icons/. There is no stylesheet: nothing QuickTS draws needs styling beyond the Shell’s own. The uuid is written down once, in metadata.json, and everything else reads it from there.

11

Releasing

Set version-name in metadata.json and version in package.json, commit, then tag and push. The release workflow checks the tag against both files before building, so it cannot publish a tag whose version disagrees with either.

$ git tag -a v0.1.1 -m 'release v0.1.1'
$ git push origin v0.1.1

12

Development

just                 # list every recipe
just test            # unit suite
just test-docs       # this site, in Chromium and Firefox
just lint            # eslint, prettier, gschema, shellcheck
just ci              # what CI runs: lint, tests, docs, security, build
just test-live       # headless Shell, bundle and LocalAPI checks
just localapi-check  # modules/io.js against this machine's daemon
just run             # a Shell in a window (needs mutter-devkit)
just docs            # serve this site on localhost:8000

Toolchain versions live in mise.toml and commands in the justfile; just setup installs both and checks for gjs, glib-compile-schemas and gnome-shell, which have to match the running Shell.