Add direct local Hermes support

Author: itsdodobitch

README.md

@@ -1,10 +1,10 @@
 # Security Model
 
-Hermes Desktop is a native macOS client for Hermes that talks directly to the
-selected host over SSH.
+Hermes Desktop is a native macOS client for Hermes that operates directly on
+this Mac or connects to another machine over SSH.
 
-The host stays the source of truth. The app does not introduce a gateway API,
-background daemon, local mirror, or separate sync layer.
+The active Hermes machine stays the source of truth. The app does not introduce
+a gateway API, background daemon, synchronized mirror, or separate sync layer.
 
 This document describes the current implementation in this repository. It is
 not a promise about future packaging, signing, or infrastructure changes.
@@ -16,17 +16,24 @@ Hermes Desktop runs as a normal macOS app on your Mac.
 Local execution includes:
 
 - the app UI and local state handling
-- `/usr/bin/ssh` for all host communication
-- a local embedded terminal session that opens an SSH shell to the selected
-  host
+- direct `/bin/sh` service commands when the connection type is `This Mac`
+- a local embedded terminal when the connection type is `This Mac`
+- `/usr/bin/ssh` and an embedded SSH shell when the connection type is
+  `SSH Host`
 - the built-in update check, which requests the latest Hermes Desktop release
   metadata from the GitHub Releases API
 
 The app does not install a helper service on the host or on your Mac.
 
-## What Executes Remotely Over SSH
+Direct-local commands run with the current macOS user's permissions against
+that account's real Hermes files. The app reuses the same `HERMES_HOME`, named
+profile, custom-home, PATH, Hermes CLI, service, and terminal bootstrap rules
+used for SSH connections.
 
-Hermes Desktop uses SSH to execute commands on the selected host.
+## What Can Execute Remotely Over SSH
+
+For an `SSH Host` connection, Hermes Desktop uses SSH to execute commands on
+the selected host.
 
 Current remote execution includes:
 
@@ -35,7 +42,7 @@ Current remote execution includes:
 - remote shell startup for the embedded terminal
 - remote `hermes` CLI invocations for in-app chat and session resume flows
 
-The app therefore depends on the remote SSH environment you already trust:
+SSH mode therefore depends on the remote SSH environment you already trust:
 
 - SSH access must already work from Terminal on your Mac
 - `python3` must exist on the host for service-style RPC requests
@@ -51,12 +58,12 @@ Hermes Desktop stores a small amount of local state under:
 Current files written there include:
 
 - `connections.json`
-  Saved connection definitions such as label, SSH alias or host, user, port,
-  and selected Hermes profile
+  Saved connection definitions including connection type, label, SSH routing
+  fields when applicable, and the selected Hermes profile or custom home
 - `preferences.json`
   App preferences and lightweight workspace state such as last-used
   connection, terminal theme and font preferences, app appearance preference,
-  background image metadata, update-check preference, bookmarked remote files,
+  background image metadata, update-check preference, bookmarked Hermes files,
   pinned sessions, sidebar order, and workflow presets
 
 If you choose a custom appearance background image, Hermes Desktop copies that
@@ -69,40 +76,41 @@ support directory is created with private directory permissions (`0700`).
 They are ordinary JSON files under your macOS user account, not Keychain
 entries.
 
-The app also creates SSH control sockets under:
+For SSH connections, the app also creates control sockets under:
 
 `/tmp/hd-<uid>`
 
 That directory is also created with private directory permissions (`0700`).
 
 ## What Is Not Stored Locally
 
-Hermes Desktop does not maintain a local mirror of Hermes host state.
+Hermes Desktop does not maintain a synchronized mirror of Hermes state.
 
 In the current implementation, it does not store these Hermes artifacts as a
-local source of truth:
+second source of truth:
 
-- remote session databases and transcripts
-- remote Kanban databases
-- remote cron job definitions
-- remote Hermes skill directories
-- remote workspace files as a synchronized mirror
+- session databases and transcripts
+- Kanban databases
+- cron job definitions
+- Hermes skill directories
+- workspace files as a synchronized mirror
 
 Unsaved edits can still exist transiently in app memory while you are working,
-but the app's design is to read and write the canonical state on the host.
+but the app's design is to read and write the canonical state on the active
+Hermes machine.
 
 Workflow presets are the notable local exception: they are intentionally stored
-as lightweight launch helpers on your Mac, scoped to the selected host/profile,
-and used only to seed a fresh remote Terminal session. They are not a local
-mirror of remote Hermes state.
+as lightweight launch helpers on your Mac, scoped to the active
+connection/profile, and used only to seed a fresh local or SSH Terminal
+session. They are not a mirror of Hermes state.
 
 ## Secrets And Credentials
 
 Hermes Desktop does not ask you to enter an SSH password into the app.
 
-Current connection profiles store routing details such as alias, host, user,
-port, and Hermes profile name. They do not contain SSH private keys, API keys,
-or a stored SSH password.
+Current connection profiles store the connection type, Hermes profile details,
+and—when using SSH—routing details such as alias, host, user, and port. They do
+not contain SSH private keys, API keys, or a stored SSH password.
 
 The app assumes SSH authentication is already handled by your existing macOS
 and SSH setup.
@@ -113,7 +121,7 @@ Hermes Desktop keeps its network surface intentionally small.
 
 In the current implementation, network calls are:
 
-- SSH connections to the host you explicitly configure
+- SSH connections only for hosts you explicitly configure as `SSH Host`
 - an optional GitHub API request to
   `https://api.github.com/repos/dodo-reach/hermes-desktop/releases/latest`
   when checking whether a newer Hermes Desktop version exists
@@ -133,8 +141,8 @@ If you want to validate the app before trusting it:
 - verify the installed bundle with
   `codesign --verify --deep --strict /Applications/HermesDesktop.app`
 - observe live connections with Little Snitch, LuLu, `lsof`, or `nettop`
-- compare this document with the current code, especially the SSH transport,
-  local storage, update check, and packaging scripts
+- compare this document with the current code, especially the local/SSH
+  transport switch, local storage, update check, and packaging scripts
 
 For release-specific details and the limits of those checks, see
 [docs/distribution.md](docs/distribution.md).

SECURITY.md

@@ -566,7 +566,11 @@ final class AppState: ObservableObject {
         guard !profile.isDefault && profile.name != "default" else {
             activeAlert = AppAlert(
                 title: L10n.string("Default profile cannot be deleted"),
-                message: L10n.string("Hermes Desktop will not delete ~/.hermes from the host. Use Stop Tracking if you only want to hide the profile locally.")
+                message: L10n.string(
+                    activeConnection.kind == .local
+                        ? "Hermes Desktop will not delete ~/.hermes from this Mac. Use Stop Tracking if you only want to hide the profile in the app."
+                        : "Hermes Desktop will not delete ~/.hermes from the host. Use Stop Tracking if you only want to hide the profile locally."
+                )
             )
             return
         }
@@ -636,14 +640,23 @@ final class AppState: ObservableObject {
                 guard connectionTestRequestID == requestID else { return }
                 isBusy = false
                 let home = response.remoteHome.trimmingCharacters(in: .whitespacesAndNewlines)
-                setStatusMessage(L10n.string("SSH and python3 OK for %@", profile.label))
-                let messageLines = [
-                    L10n.string("SSH and python3 are available for this Hermes host."),
-                    home.isEmpty ? nil : L10n.string("Remote HOME: %@", home)
-                ].compactMap { $0 }
+                setStatusMessage(
+                    profile.kind == .local
+                        ? L10n.string("Local Hermes and python3 OK for %@", profile.label)
+                        : L10n.string("SSH and python3 OK for %@", profile.label)
+                )
+                let messageLines: [String?] = profile.kind == .local
+                    ? [
+                        L10n.string("Hermes Desktop can run local commands with python3 using your current macOS account."),
+                        home.isEmpty ? nil : L10n.string("Local HOME: %@", home)
+                    ]
+                    : [
+                        L10n.string("SSH and python3 are available for this Hermes host."),
+                        home.isEmpty ? nil : L10n.string("Remote HOME: %@", home)
+                    ]
                 activeAlert = AppAlert(
                     title: L10n.string("Connection OK"),
-                    message: messageLines.joined(separator: "\n")
+                    message: messageLines.compactMap { $0 }.joined(separator: "\n")
                 )
             } catch {
                 guard connectionTestRequestID == requestID else { return }
@@ -687,7 +700,11 @@ final class AppState: ObservableObject {
             guard isActiveWorkspace(profile) else { return }
             overview = nil
             overviewError = error.localizedDescription
-            setStatusMessage(L10n.string("Unable to refresh remote discovery"))
+            setStatusMessage(L10n.string(
+                profile.kind == .local
+                    ? "Unable to refresh local discovery"
+                    : "Unable to refresh remote discovery"
+            ))
         }
     }
 
@@ -935,7 +952,7 @@ final class AppState: ObservableObject {
             guard isActiveWorkspace(profile) else { return }
             isLoadingWorkspaceFileBrowser = false
             workspaceFileBrowserError = error.localizedDescription
-            setStatusMessage(L10n.string("Unable to browse remote files"))
+            setStatusMessage(L10n.string("Unable to browse files"))
         }
     }
 
@@ -1232,7 +1249,11 @@ final class AppState: ObservableObject {
             await loadSessions(reset: true)
             await loadUsage(forceRefresh: true)
             isDeletingSession = false
-            setStatusMessage(L10n.string("Session deleted locally and on the remote Hermes host"))
+            setStatusMessage(L10n.string(
+                profile.kind == .local
+                    ? "Session deleted from this Mac’s real Hermes data"
+                    : "Session deleted locally and on the remote Hermes host"
+            ))
         } catch {
             guard isActiveWorkspace(profile) else { return }
             isDeletingSession = false

Sources/HermesDesktop/App/AppState.swift

@@ -1,7 +1,15 @@
 import Foundation
 
+enum ConnectionKind: String, Codable, CaseIterable, Identifiable {
+    case ssh
+    case local
+
+    var id: String { rawValue }
+}
+
 struct ConnectionProfile: Codable, Identifiable, Equatable, Hashable {
     var id: UUID
+    var kind: ConnectionKind
     var label: String
     var sshAlias: String
     var sshHost: String
@@ -15,6 +23,7 @@ struct ConnectionProfile: Codable, Identifiable, Equatable, Hashable {
 
     init(
         id: UUID = UUID(),
+        kind: ConnectionKind = .ssh,
         label: String = "",
         sshAlias: String = "",
         sshHost: String = "",
@@ -27,6 +36,7 @@ struct ConnectionProfile: Codable, Identifiable, Equatable, Hashable {
         lastConnectedAt: Date? = nil
     ) {
         self.id = id
+        self.kind = kind
         self.label = label
         self.sshAlias = sshAlias
         self.sshHost = sshHost
@@ -39,6 +49,37 @@ struct ConnectionProfile: Codable, Identifiable, Equatable, Hashable {
         self.lastConnectedAt = lastConnectedAt
     }
 
+    private enum CodingKeys: String, CodingKey {
+        case id
+        case kind
+        case label
+        case sshAlias
+        case sshHost
+        case sshPort
+        case sshUser
+        case hermesProfile
+        case customHermesHomePath
+        case createdAt
+        case updatedAt
+        case lastConnectedAt
+    }
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = try container.decode(UUID.self, forKey: .id)
+        kind = try container.decodeIfPresent(ConnectionKind.self, forKey: .kind) ?? .ssh
+        label = try container.decode(String.self, forKey: .label)
+        sshAlias = try container.decodeIfPresent(String.self, forKey: .sshAlias) ?? ""
+        sshHost = try container.decodeIfPresent(String.self, forKey: .sshHost) ?? ""
+        sshPort = try container.decodeIfPresent(Int.self, forKey: .sshPort)
+        sshUser = try container.decodeIfPresent(String.self, forKey: .sshUser) ?? ""
+        hermesProfile = try container.decodeIfPresent(String.self, forKey: .hermesProfile)
+        customHermesHomePath = try container.decodeIfPresent(String.self, forKey: .customHermesHomePath)
+        createdAt = try container.decode(Date.self, forKey: .createdAt)
+        updatedAt = try container.decode(Date.self, forKey: .updatedAt)
+        lastConnectedAt = try container.decodeIfPresent(Date.self, forKey: .lastConnectedAt)
+    }
+
     var trimmedAlias: String? {
         let value = sshAlias.trimmingCharacters(in: .whitespacesAndNewlines)
         return value.isEmpty ? nil : value
@@ -202,7 +243,10 @@ struct ConnectionProfile: Codable, Identifiable, Equatable, Hashable {
     }
 
     var workspaceScopeFingerprint: String {
-        [
+        if kind == .local {
+            return "\(localConnectionIdentity)|\(remoteHermesHomePath)"
+        }
+        return [
             effectiveTarget,
             trimmedUser ?? "",
             resolvedPort.map(String.init) ?? "",
@@ -211,15 +255,25 @@ struct ConnectionProfile: Codable, Identifiable, Equatable, Hashable {
     }
 
     var hostConnectionFingerprint: String {
-        [
+        if kind == .local {
+            return localConnectionIdentity
+        }
+        return [
             effectiveTarget,
             trimmedUser ?? "",
             resolvedPort.map(String.init) ?? ""
         ].joined(separator: "|")
     }
 
     var effectiveTarget: String {
-        trimmedAlias ?? trimmedHost ?? ""
+        if kind == .local {
+            return "This Mac"
+        }
+        return trimmedAlias ?? trimmedHost ?? ""
+    }
+
+    var localConnectionIdentity: String {
+        "local:v1"
     }
 
     var usesAliasSourceOfTruth: Bool {
@@ -235,12 +289,19 @@ struct ConnectionProfile: Codable, Identifiable, Equatable, Hashable {
     }
 
     var displayDestination: String {
+        if kind == .local {
+            return "This Mac"
+        }
         guard let user = trimmedUser else {
             return effectiveTarget
         }
         return "\(user)@\(effectiveTarget)"
     }
 
+    var localizedDisplayDestination: String {
+        kind == .local ? L10n.string("This Mac") : displayDestination
+    }
+
     var isValid: Bool {
         validationError == nil
     }
@@ -250,7 +311,11 @@ struct ConnectionProfile: Codable, Identifiable, Equatable, Hashable {
             return "Name is required."
         }
 
-        return sshValidationError
+        if kind == .ssh, let sshValidationError {
+            return sshValidationError
+        }
+
+        return hermesWorkspaceValidationError
     }
 
     var sshValidationError: String? {
@@ -270,6 +335,10 @@ struct ConnectionProfile: Codable, Identifiable, Equatable, Hashable {
             return error
         }
 
+        return hermesWorkspaceValidationError
+    }
+
+    private var hermesWorkspaceValidationError: String? {
         if trimmedHermesProfile != nil && trimmedCustomHermesHomePath != nil {
             return "Choose either a Hermes profile or a custom Hermes home path."
         }