Tailscale Widget

A native KDE Plasma 6 widget to control Tailscale — status, connect/disconnect, profiles, exit nodes, and your whole tailnet at a glance.

---

Table of Contents

• Features
• Screenshots
• Requirements
• Installation
  • Quick install
  • Manual build
  • One-time permission setup
• Usage
• Configuration
• Uninstall
• Architecture
• Contributing
• License
• Maintainers

Features

• Connection toggle — connect or disconnect from your tailnet with a single switch.
• Live status — polls tailscale status every 5 seconds; an online/offline dot and tooltip always reflect the real state.
• Profile switching — jump between Tailscale accounts from a dropdown.
• Exit nodes — route traffic through any peer advertising itself as an exit node, with optional LAN access; clear it just as easily.
• Device list — browse every peer in your tailnet with OS-aware icons, online status, and IP addresses.
• Ping peers — ping any device straight from its row and see the result inline.
• Copy your IP — one click copies this machine's Tailscale IP to the clipboard.
• Sort & filter — order devices by status, name, or OS; optionally hide offline devices.
• List or grid layout — display your tailnet as rows or tiles.
• Custom header icon — pick any theme icon or your own image for the widget logo.
• Panel or desktop — shows a compact icon in the panel with a popup, or the full view on the desktop.
• No sudo at runtime — commands run as your local user once the operator is set (the widget guides you through the one-time step).

Screenshots

Replace the placeholder images below with real captures. See docs/images/README.md for how and what to capture.

Full view — connected

Device list & exit node selector

Configuration

Requirements

• KDE Plasma 6 (uses the Plasma 6 applet API, minimum version 6.0)
• Qt 6.5+ and KDE Frameworks 6
• Tailscale installed, with the tailscale CLI on your PATH
• Build tools: CMake 3.16+, a C++17 compiler, and the KDE extra-cmake-modules

Install build dependencies

Arch / EndeavourOS / Manjaro

sudo pacman -S --needed base-devel cmake extra-cmake-modules qt6-base qt6-declarative plasma-workspace ki18n kirigami

Fedora / KDE Spin

sudo dnf install cmake extra-cmake-modules gcc-c++ qt6-qtbase-devel qt6-qtdeclarative-devel kf6-ki18n-devel kf6-kirigami-devel plasma-workspace-devel

openSUSE Tumbleweed

sudo zypper install cmake extra-cmake-modules gcc-c++ qt6-base-devel qt6-declarative-devel ki18n-devel kirigami6-devel plasma6-workspace-devel

Kubuntu / Debian

sudo apt install cmake extra-cmake-modules g++ qt6-base-dev qt6-declarative-dev libkf6i18n-dev libkf6kirigami-dev plasma-workspace-dev

Installation

Quick install

git clone https://github.com/DeadIndian/tailscale-widget.git
cd tailscale-widget
./install.sh

The script configures the project with CMake, builds the C++ backend, installs the plasmoid, and restarts plasmashell so the widget is immediately available. Then add it: right-click your panel or desktop → Add Widgets → search "Tailscale".

Manual build

If you'd rather run the steps yourself:

cmake -B build -DCMAKE_INSTALL_PREFIX="$(kf6-config --prefix)"
cmake --build build
cmake --install build       # may need sudo depending on your prefix
kquitapp6 plasmashell && kstart plasmashell

One-time permission setup

Tailscale requires an operator to be set so a normal user can run up/down without sudo. The widget detects when this is missing and shows a banner with the fix. Run it once:

sudo tailscale set --operator=$USER

After that, everything works without elevated privileges.

Usage

1. Add the widget to your panel or desktop (Add Widgets → Tailscale).
2. Click the panel icon to open the popup (on the desktop the full view shows directly).
3. Use the Connection switch to connect or disconnect.
4. Pick a profile or exit node from their dropdowns (each can be hidden in settings).
5. Browse your devices, ping any peer, or copy an IP with the button in the header.

Configuration

Right-click the widget → Configure Tailscale…

General

Setting	Default	Description
Show profile switcher	on	Show the account/profile dropdown
Show exit node switcher	on	Show the exit node selector
Show device list	on	Show the tailnet peer list

Appearance

Setting	Default	Description
Show header logo	on	Show the logo at the top of the full view
Logo icon	network-vpn	Any theme icon or a custom image
Device layout	list	Display devices as a list or a grid
Sort devices by	status	Status (online first), name, or OS
Hide offline devices	off	Hide peers that are currently offline
Show IP addresses	on	Show each device's Tailscale IP

Uninstall

./uninstall.sh

This removes the installed plasmoid and backend, then restarts plasmashell.

Architecture

A hybrid C++/QML plasmoid:

• Backend (src/) — a TailscaleBackend QObject exposed to QML. It wraps the tailscale CLI via QProcess, always passing arguments as a list (never a shell string) and validating profile/host arguments so nothing can be interpreted as a flag or injected. A PeerModel exposes the tailnet as a list model.
• Frontend (package/contents/ui/) — QML built on Plasma and Kirigami components for a native look, with KSortFilterProxyModel driving sort/filter of the device list.

See spec.md and reference.md for the original design notes.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for the build/test workflow and coding guidelines, and note that this project follows a Code of Conduct.

License

This project is licensed under the GNU General Public License v3.0 or later. See LICENSE for the full text.

Maintainers

• Dead Indian — gollabharath2007@gmail.com (@DeadIndian)