Pywebview nix

docs/02-usage/020_running.md

@@ -78,6 +78,7 @@ See our [advanced Docker usage](https://github.com/oraios/serena/blob/main/DOCKE
 Docker usage is subject to limitations; see the [advanced Docker usage](https://github.com/oraios/serena/blob/main/DOCKER.md) documentation for details.
 :::
 
+(nix-usage)=
 ### Using Nix
 
 If you are using Nix and [have enabled the `nix-command` and `flakes` features](https://nixos.wiki/wiki/flakes), you can run Serena using the following command:
@@ -88,6 +89,15 @@ nix run github:oraios/serena -- <command> [options]
 
 You can also install Serena by referencing this repo (`github:oraios/serena`) and using it in your Nix flake. The package is exported as `serena`.
 
+#### Linux: Native Dashboard Support
+
+On Linux, the Nix flake automatically wraps the Serena binary with the GTK 3 and WebKit2GTK libraries
+required by pywebview. This means the **native dashboard viewer** (with system tray integration) works
+out of the box — no manual installation of system packages is needed.
+
+When Serena is run via `nix run` or installed from the flake, the dashboard will open as a native
+window (same as on Windows and macOS) rather than falling back to the web browser.
+
 (start-mcp-server)=
 ## Running the MCP Server
 

docs/02-usage/060_dashboard.md

@@ -22,7 +22,9 @@ Both can be configured in Serena's [configuration](050_configuration) file (`ser
 The dashboard is a web application, which is opened via a native application wrapper on Windows and macOS,
 where it will appear in the system tray. **Click on the tray icon** to open the application window.
 
-On Linux, native app support is difficult to provide, so the dashboard will be opened in your default web browser instead.  
+On Linux, native app support requires GTK 3 and WebKit2GTK. When running Serena via the [Nix flake](nix-usage),
+these libraries are bundled automatically, so the native dashboard viewer (with system tray) works out of the box.
+Without the Nix wrapper, the dashboard will be opened in your default web browser instead.
 
 By default, the dashboard can be accessed at `http://localhost:24282/dashboard/index.html`,
 but a higher port may be used if the default port is unavailable/multiple instances are running.
@@ -61,7 +63,7 @@ to the `start-mcp-server` CLI command.
 On Windows and macOS, you can conveniently open the dashboard at any time by clicking on the tray icon, so automatic
 opening is not a requirement to be able to access the dashboard on these platforms.
 
-On Linux, access to the dashboard is more cumbersome without native app support.  
+On Linux without the Nix wrapper, access to the dashboard is more cumbersome without native app support.
 Yet you may still access it by
 * asking the LLM to "open the Serena dashboard", which will open the dashboard in your default browser
   (the tool `open_dashboard` is enabled for this purpose, provided that the dashboard is active, 

flake.nix

@@ -86,9 +86,43 @@
     in rec {
       formatter = pkgs.alejandra;
 
+      # GTK/WebKit libraries needed by pywebview and pystray on Linux.
+      gtkDeps = lib.optionals pkgs.stdenv.isLinux (with pkgs; [
+        gtk3
+        webkitgtk_4_1
+        glib
+        pango
+        gdk-pixbuf
+        gobject-introspection
+        libayatana-appindicator
+      ]);
+
       packages = {
         serena-env = pythonSet.mkVirtualEnv "serena-env" workspace.deps.default;
-        serena = pkgs.runCommand "serena" {
+        serena = let
+          unwrapped = pkgs.runCommand "serena-unwrapped" {} ''
+            mkdir -p $out/bin
+            ln -s ${packages.serena-env}/bin/serena $out/bin/serena
+          '';
+        in
+          pkgs.stdenv.mkDerivation {
+            pname = "serena";
+            version = "0.1.4";
+            dontUnpack = true;
+            nativeBuildInputs = lib.optionals pkgs.stdenv.isLinux [pkgs.makeWrapper];
+            installPhase =
+              if pkgs.stdenv.isLinux
+              then ''
+                mkdir -p $out/bin
+                makeWrapper ${unwrapped}/bin/serena $out/bin/serena \
+                  --set GI_TYPELIB_PATH "${lib.makeSearchPath "lib/girepository-1.0" gtkDeps}" \
+                  --prefix LD_LIBRARY_PATH : "${lib.makeLibraryPath gtkDeps}" \
+                  --set SERENA_NIX_WRAPPED "1"
+              ''
+              else ''
+                mkdir -p $out/bin
+                ln -s ${unwrapped}/bin/serena $out/bin/serena
+              '';
             meta = {
               description = "A powerful coding agent toolkit providing semantic retrieval and editing capabilities (MCP server & Agno integration)";
               homepage = "https://oraios.github.io/serena";
@@ -97,10 +131,7 @@
               license = pkgs.lib.licenses.mit;
               platforms = lib.platforms.all;
             };
-          } ''
-          mkdir -p $out/bin
-          ln -s ${packages.serena-env}/bin/serena $out/bin/serena
-        '';
+          };
         default = packages.serena;
       };
 

src/serena/dashboard.py

@@ -716,9 +716,14 @@ def is_current_platform_supported() -> bool:
         """
         :return: whether the current platform supports the dashboard viewer
         """
-        # We fully support the dashboard viewer (with system tray) only on Windows and macOS.
-        # Linux support is problematic; see https://github.com/oraios/serena/pull/1117#issuecomment-4128753943
-        return sys.platform in ("win32", "darwin")
+        # We fully support the dashboard viewer (with system tray) on Windows and macOS.
+        # Linux support is problematic in general (see https://github.com/oraios/serena/pull/1117#issuecomment-4128753943),
+        # but works when the required GTK/WebKit libraries are available, e.g. when running via the Nix flake.
+        if sys.platform in ("win32", "darwin"):
+            return True
+        if sys.platform == "linux" and os.environ.get("SERENA_NIX_WRAPPED"):
+            return True
+        return False
 
     def run(self) -> None:
         # set app id (avoid app being lumped together with other Python-based apps in Windows taskbar)