Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

desktop(linux): list an AppImage in the app launcher, with its icon

bubu-dudu52faefc5f7e8
diff --git a/desktop/lib/app_shell.dart b/desktop/lib/app_shell.dart
index ef847a975..473997aae 100644
--- a/desktop/lib/app_shell.dart
+++ b/desktop/lib/app_shell.dart
@@ -12,6 +12,7 @@ import 'package:flutter_web_plugins/url_strategy.dart';
import 'core/crash_log.dart';
import 'core/desktop_window.dart';
+import 'core/linux_app_image.dart';
import 'screens/login_screen.dart';
import 'state/app_state.dart';
import 'stats/stats_lifecycle.dart';
@@ -90,6 +91,9 @@ Future<void> startHarness({
),
),
);
+ // After the first frame is on its way: a launcher entry is not worth
+ // holding the window up for.
+ unawaited(registerAppImageLauncher());
}
class HarnessApp extends StatelessWidget {
diff --git a/desktop/lib/core/linux_app_image.dart b/desktop/lib/core/linux_app_image.dart
new file mode 100644
index 000000000..08d2f7339
--- /dev/null
+++ b/desktop/lib/core/linux_app_image.dart
@@ -0,0 +1,101 @@
+import 'dart:io';
+
+import '../logging/app_log.dart';
+import 'runtime_platform.dart';
+
+/// The window's app id (`APPLICATION_ID` in linux/CMakeLists.txt). A launcher
+/// entry names it as `StartupWMClass` so a dock matches the running window to
+/// the entry — and draws its icon — instead of a generic gear.
+const kLinuxAppId = 'com.autonomous.harness';
+
+/// Puts Harness in the desktop's application list when it runs from an
+/// AppImage nothing installed.
+///
+/// An AppImage is one executable file. Double-clicked from Downloads it runs,
+/// but no desktop registers it: "Show Applications" never lists it, and the
+/// dock shows its window with a gear. The website installer
+/// (`website/scripts/desktop-install.sh`) writes the launcher entry and icon
+/// itself; this does the same for an AppImage started any other way, which the
+/// AppImage runtime announces by setting `APPIMAGE` to the file's path.
+///
+/// An entry that already launches an AppImage still on disk is left alone —
+/// the installer's, or one this wrote for a copy elsewhere — so a second copy
+/// cannot take the entry over. A missing entry, or one whose file has gone
+/// (moved or deleted), is (re)written. Never throws: a launcher entry is not
+/// worth failing a launch over.
+Future<void> registerAppImageLauncher({
+ Map<String, String>? environment,
+ String? executable,
+}) async {
+ if (!RuntimePlatform.isLinux && environment == null) return;
+ final env = environment ?? RuntimePlatform.environment;
+ final appImage = env['APPIMAGE'];
+ final home = env['HOME'];
+ if (appImage == null || appImage.isEmpty || home == null || home.isEmpty) {
+ return;
+ }
+ try {
+ final dataHome = (env['XDG_DATA_HOME']?.isNotEmpty ?? false)
+ ? env['XDG_DATA_HOME']!
+ : '$home/.local/share';
+ final entry = File('$dataHome/applications/harness.desktop');
+ if (await entry.exists()) {
+ final target = _execTarget(await entry.readAsString());
+ if (target != null && await File(target).exists()) return;
+ }
+ // The bundle's icon sits beside the executable, inside the mounted image.
+ final bundleIcon = File(
+ '${File(executable ?? Platform.resolvedExecutable).parent.path}'
+ '/harness.png',
+ );
+ final icon = File('$dataHome/icons/harness.png');
+ if (await bundleIcon.exists()) {
+ await icon.parent.create(recursive: true);
+ await bundleIcon.copy(icon.path);
+ }
+ await entry.parent.create(recursive: true);
+ await entry.writeAsString(
+ '[Desktop Entry]\n'
+ 'Type=Application\n'
+ 'Name=Harness\n'
+ 'Comment=Attach terminals to the agents running on your Harness machines\n'
+ 'Exec=${_quoteExec(appImage)}\n'
+ 'Icon=${icon.path}\n'
+ 'Terminal=false\n'
+ 'Categories=Development;\n'
+ 'StartupWMClass=$kLinuxAppId\n',
+ );
+ appLog.info('app', 'registered launcher entry for $appImage');
+ } on FileSystemException catch (error) {
+ appLog.warn('app', 'could not register a launcher entry: ${error.message}');
+ }
+}
+
+/// The program an entry's `Exec=` line starts, unquoted; null when it has none.
+String? _execTarget(String entry) {
+ for (final line in entry.split('\n')) {
+ if (!line.startsWith('Exec=')) continue;
+ final value = line.substring(5).trim();
+ if (value.startsWith('"')) {
+ final end = value.indexOf('"', 1);
+ if (end < 0) return null;
+ return value
+ .substring(1, end)
+ .replaceAllMapped(RegExp(r'\\(.)'), (match) => match[1]!);
+ }
+ final space = value.indexOf(' ');
+ return space < 0 ? value : value.substring(0, space);
+ }
+ return null;
+}
+
+/// A path as the Desktop Entry spec wants it in `Exec=`: quoted when it holds
+/// a character the launcher would otherwise split or expand on.
+String _quoteExec(String path) {
+ if (!RegExp(r'''[\s"'\\$`<>~|&;*?#()]''').hasMatch(path)) return path;
+ final escaped = path.replaceAllMapped(
+ RegExp(r'["`$\\]'),
+ (match) => '\\${match[0]}',
+ );
+ return '"$escaped"';
+}
diff --git a/desktop/scripts/upload-desktop-linux.sh b/desktop/scripts/upload-desktop-linux.sh
index b5df96803..d3fa890a9 100755
--- a/desktop/scripts/upload-desktop-linux.sh
+++ b/desktop/scripts/upload-desktop-linux.sh
@@ -222,6 +222,8 @@ mkdir -p "$APPDIR/usr/bin"
cp -a "$BUNDLE_DIR/." "$APPDIR/usr/bin/"
ln -s usr/bin/harness "$APPDIR/AppRun"
cp "$BUNDLE_DIR/harness.png" "$APPDIR/harness.png"
+# StartupWMClass is the window's app id (APPLICATION_ID, linux/CMakeLists.txt): how a dock matches the
+# running window to this entry instead of drawing it with a generic icon.
cat > "$APPDIR/harness.desktop" <<EOF
[Desktop Entry]
Type=Application
@@ -231,6 +233,7 @@ Exec=harness
Icon=harness
Categories=Development;
Terminal=false
+StartupWMClass=com.autonomous.harness
EOF
APPIMAGE_ARCH="$([ "$RELEASE_ARCH" = "arm64" ] && echo aarch64 || echo x86_64)"
diff --git a/desktop/test/linux_app_image_test.dart b/desktop/test/linux_app_image_test.dart
new file mode 100644
index 000000000..e38ac51bf
--- /dev/null
+++ b/desktop/test/linux_app_image_test.dart
@@ -0,0 +1,79 @@
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/linux_app_image.dart';
+
+void main() {
+ late Directory root;
+ late String home, bundle;
+
+ setUp(() {
+ root = Directory.systemTemp.createTempSync('harness-appimage-');
+ home = '${root.path}/home';
+ bundle = '${root.path}/mount/usr/bin';
+ Directory(bundle).createSync(recursive: true);
+ File('$bundle/harness.png').writeAsBytesSync([1, 2, 3]);
+ File('$bundle/harness').writeAsStringSync('');
+ });
+ tearDown(() => root.deleteSync(recursive: true));
+
+ File entry() => File('$home/.local/share/applications/harness.desktop');
+
+ Future<void> launch(String appImage) async {
+ File(appImage)
+ ..parent.createSync(recursive: true)
+ ..writeAsStringSync('');
+ await registerAppImageLauncher(
+ environment: {'APPIMAGE': appImage, 'HOME': home},
+ executable: '$bundle/harness',
+ );
+ }
+
+ test('an AppImage started from Downloads lands in the app list', () async {
+ await launch('$home/Downloads/Harness-linux-x64.AppImage');
+ final text = entry().readAsStringSync();
+ expect(text, contains('Exec=$home/Downloads/Harness-linux-x64.AppImage\n'));
+ expect(text, contains('StartupWMClass=com.autonomous.harness\n'));
+ expect(text, contains('Icon=$home/.local/share/icons/harness.png\n'));
+ expect(File('$home/.local/share/icons/harness.png').readAsBytesSync(), [
+ 1,
+ 2,
+ 3,
+ ]);
+ });
+
+ test('a path with spaces is quoted for the launcher', () async {
+ await launch('$home/My Apps/Harness.AppImage');
+ expect(
+ entry().readAsStringSync(),
+ contains('Exec="$home/My Apps/Harness.AppImage"\n'),
+ );
+ });
+
+ test('an entry for a copy still on disk is not taken over', () async {
+ await launch('$home/.local/opt/Harness.AppImage');
+ await launch('$home/Downloads/Harness-linux-x64.AppImage');
+ expect(
+ entry().readAsStringSync(),
+ contains('Exec=$home/.local/opt/Harness.AppImage\n'),
+ );
+ });
+
+ test('an entry whose AppImage is gone follows the one running', () async {
+ await launch('$home/My Apps/Harness.AppImage');
+ File('$home/My Apps/Harness.AppImage').deleteSync();
+ await launch('$home/Downloads/Harness-linux-x64.AppImage');
+ expect(
+ entry().readAsStringSync(),
+ contains('Exec=$home/Downloads/Harness-linux-x64.AppImage\n'),
+ );
+ });
+
+ test('not started from an AppImage, nothing is written', () async {
+ await registerAppImageLauncher(
+ environment: {'HOME': home},
+ executable: '$bundle/harness',
+ );
+ expect(entry().existsSync(), isFalse);
+ });
+}
diff --git a/website/scripts/desktop-install.sh b/website/scripts/desktop-install.sh
index 4fe7caedd..586e53246 100755
--- a/website/scripts/desktop-install.sh
+++ b/website/scripts/desktop-install.sh
@@ -263,6 +263,9 @@ mkdir -p "$ICON_DIR" 2>/dev/null || true
DESKTOP_ENTRY_DIR="$HOME/.local/share/applications"
mkdir -p "$DESKTOP_ENTRY_DIR" 2>/dev/null || true
if [ -d "$DESKTOP_ENTRY_DIR" ]; then
+ # StartupWMClass ties the running window — app id com.autonomous.harness, set in the desktop
+ # repo's linux/CMakeLists.txt — to this entry. Without it GNOME's dock cannot match the two and
+ # shows the running app with a generic gear.
cat > "$DESKTOP_ENTRY_DIR/harness.desktop" <<EOF
[Desktop Entry]
Type=Application
@@ -272,6 +275,7 @@ Exec=$DESTINATION
Icon=$ICON_DIR/harness.png
Terminal=false
Categories=Development;
+StartupWMClass=com.autonomous.harness
EOF
fi