A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.
Installing Gentle Dot
Gentle Dot ships as a self-contained app: it carries its own Node runtime, the assistant engine, and a fallback Engram. Nothing else needs to be installed first.
macOS
Requirements: a Mac with Apple Silicon (M1 or later) and macOS 12.3 or later.
Install
- Open
Gentle Dot_<version>_aarch64.dmg. - Drag Gentle Dot onto the Applications folder in the window that opens.
- Eject the disk image.
First open
The app is not notarized by Apple, so macOS blocks the first open. Approve it once:
- macOS 15 (Sequoia) and later:
- Open Gentle Dot from Applications. macOS says it cannot verify the app; click Done.
- Open System Settings → Privacy & Security, scroll to Security, and click Open Anyway next to the Gentle Dot message.
- Confirm with Open Anyway and your password.
- macOS 12 to 14: Control-click Gentle Dot in Applications, choose Open, then Open again.
Alternative from Terminal (any version), which removes the download quarantine from the app:
xattr -dr com.apple.quarantine "/Applications/Gentle Dot.app"
Only do this for a copy you got from someone you trust.
Permissions for computer control
Computer control needs two macOS permissions. Open Connectors → Computer in Gentle Dot and click Grant for each, or add Gentle Dot by hand:
- System Settings → Privacy & Security → Accessibility: lets the assistant click and type.
- System Settings → Privacy & Security → Screen Recording (named Screen & System Audio Recording on macOS 15): lets the assistant take screenshots.
Restart Gentle Dot after granting Screen Recording.
macOS ties these grants to the app's signature. A DMG signed with a stable identity (see below) keeps them across updates. A build signed ad hoc (the default) gets a new signature on every build, so after an update the old entries stop working: remove Gentle Dot from both lists with the minus button and grant again.
Where data lives
| What | Where |
|---|---|
Settings, conversations, logs (daemon.log), the engine's own files |
~/.gentle-dot/ |
Memory (Engram, project gentle-dot) |
~/.engram/, shared with any other Engram user on this Mac |
| Launch at login (when turned on) | a LaunchAgent in ~/Library/LaunchAgents/ |
The app itself never changes after install; everything it writes goes to the folders above.
Uninstall
In the menu bar item, turn off Launch at login, then quit Gentle Dot.
Drag
/Applications/Gentle Dot.appto the Trash.Optional: remove
~/.gentle-dot/to delete settings and conversations.Optional: reset the permissions:
tccutil reset Accessibility dev.gentleman.gentle-dot tccutil reset ScreenCapture dev.gentleman.gentle-dot
Leave ~/.engram/ in place unless you want to delete every Engram memory on this Mac, not only Gentle Dot's.
Build the DMG from source
On an Apple Silicon Mac with Node 24, pnpm, Rust (rustc on PATH), and Xcode command line tools:
pnpm install
pnpm package:mac # signs ad hoc
pnpm package:mac --sign "<identity>" # or GENTLE_DOT_SIGN_IDENTITY="<identity>"
pnpm package:mac --check # also mounts the DMG and smoke-tests the copied app's daemon
To keep permissions across updates, sign every release with the same identity. scripts/package/create-signing-identity.sh creates a self-signed one named "Gentle Dot Local Signing" in the login keychain (no trust setting or password needed); its designated requirement pins the certificate (certificate leaf = H"…"), so it stays the same across builds. Keep that keychain entry: a new certificate means everyone grants the permissions once more. The first signed build asks once per signed file to use the key; choose Always Allow on the first prompt.
The command stages the runtime (build/runtime/darwin-arm64), signs the runtime's binaries, builds the release app, and writes the DMG to apps/desktop/src-tauri/target/release/bundle/dmg/. --skip-stage reuses a runtime staged earlier; --check-dmg <dmg> checks an existing DMG without building.
Windows
Requirements: Windows 10 or 11, 64-bit (x64). Computer control screenshots require Windows 10 version 2004 (build 19041) or newer: excluding Gentle Dot's windows from captures requires WDA_EXCLUDEFROMCAPTURE.
Install
- Run
Gentle Dot_<version>_x64-setup.exe. - The installer is not signed yet, so Windows SmartScreen may say Windows protected your PC. Click More info, then Run anyway. Only do this for an installer you built yourself or got from someone you trust.
- Follow the installer. It installs for your user only, in
%LOCALAPPDATA%\Gentle Dot(an update keeps the folder of the earlier install), with no administrator prompt. Where WebView2 is missing, it first runs Microsoft's WebView2 installer, which needs the internet. WebView2 ships with Windows 11 and most Windows 10 installs.
If Gentle Dot is running, the installer says Gentle Dot is running! Click OK to kill it. OK closes it at once, without the usual orderly quit, so quit it from the tray first.
First open
Open Gentle Dot from the Start menu. The first open needs the network once: the engine installs its companion packages. The computer-control emergency stop is Alt+Shift+Esc. Voice input is not available on Windows yet.
Where data lives
| What | Where |
|---|---|
| The app and its bundled runtime | the install folder, with the runtime in runtime\ |
Settings, conversations, logs (daemon.log), the engine's own files |
%USERPROFILE%\.gentle-dot\ |
| Connector secrets, encrypted for your Windows user (DPAPI) | %LOCALAPPDATA%\dev.gentleman.gentle-dot.connectors\ |
| The window's own data (WebView2) | %LOCALAPPDATA%\dev.gentleman.gentle-dot\ and %APPDATA%\dev.gentleman.gentle-dot\ |
Memory (Engram, project gentle-dot) |
%USERPROFILE%\.engram\, shared with any other Engram user on this PC |
| Launch at login (when turned on) | a Gentle Dot value under HKCU\Software\Microsoft\Windows\CurrentVersion\Run |
The app's install folder never changes after install; everything it writes goes to the folders above.
A connector secret that cannot be read
Each connector secret is one .bin file in a subfolder of %LOCALAPPDATA%\dev.gentleman.gentle-dot.connectors\. If one of those files is damaged, or was put there by something other than Gentle Dot, that secret can no longer be read or saved again. The error says The app's secure store refused it: the secret store failed: … (in the app or in %USERPROFILE%\.gentle-dot\daemon.log), and setting the connector up again does not help. When the damaged file holds the key Gentle Dot checks your connectors with, Gentle Dot says on every start that it could not check your connectors, and the connectors that need a secret stay locked. Restarting, as that notice suggests, does not help in this case.
Gentle Dot never repairs, replaces or deletes such a file, and it never keeps the secret unencrypted instead. That is on purpose. You have to remove it yourself. The file name is a hash and Gentle Dot does not show which file is broken, so remove the whole folder:
- Quit Gentle Dot from its tray icon (Quit), so it does not use the folder while you delete it.
- Delete
%LOCALAPPDATA%\dev.gentleman.gentle-dot.connectors\. Only your Windows user (or an administrator) can. - Open Gentle Dot again. This removes every connector secret, including the key that checks your connectors. On this start Gentle Dot makes a new key, so it moves
connectors.jsonaside asconnectors.rejected-<time>.jsonin%USERPROFILE%\.gentle-dot\, starts with no connectors, and says connectors were changed while it was closed. This happens even if you had no connectors, because Gentle Dot signsconnectors.jsonfrom its first start. - Add your connectors again in Connectors and sign in again.
Uninstall
- Quit Gentle Dot from its tray icon (Quit), so the assistant and its processes stop in order.
- Open Settings → Apps → Installed apps, find Gentle Dot, and choose Uninstall, or run
uninstall.exein the install folder. It removes the app, its Start menu and desktop shortcuts, its launch at login, and its registry entries. Like the installer, it asks to close Gentle Dot if it is still running. - Optional: tick Delete the application data in the uninstaller to remove the window's data (
%APPDATA%\dev.gentleman.gentle-dot\and%LOCALAPPDATA%\dev.gentleman.gentle-dot\). - Optional: remove
%USERPROFILE%\.gentle-dot\to delete settings and conversations, and%LOCALAPPDATA%\dev.gentleman.gentle-dot.connectors\to delete connector secrets. The uninstaller never touches these.
%USERPROFILE%\.gentle-dot\daemon.owner stays behind after a normal quit. It records the last launch without any authority over it, and the next launch replaces it.
Build the installer from source
On Windows 10 or 11 (x64) with Node 24, pnpm, Rust, Visual Studio's C++ build tools (for the native addon), and Go 1.25.10 or newer:
pnpm install
pnpm --filter @gentle-dot/daemon build:windows-stop -- --compiler <cl.exe> --headers <node-headers>/include/node --node-lib <node.lib>
$env:GENTLE_DOT_BUILD_GO = "C:\Program Files\Go\bin\go.exe"
pnpm package:runtime --target windows-x64
pnpm package:windows
build:windows-stopbuildspackages/daemon/native/windows-stop.node, the native stop and app channel addon. The runtime build refuses to stage without it..github/workflows/windows.ymlshows the exact compiler, headers andnode.libit uses.GENTLE_DOT_BUILD_GOmust be the full path of the realgo.exeinGOROOT\bin, not a package manager shim. gentle-pi's postinstall builds gentle-ai from source with it. Only that directory joins the installer'sPATH, which otherwise holds the staged Node and the Windows system folders.- Run both commands through pnpm: on Windows, staging calls pnpm through Node instead of spawning
pnpm.cmd. package:runtimewritesbuild/runtime/windows-x64(about 320 MB): Node from its official ZIP, Engram'sengram.exe, the daemon with its dependencies, and the web UI, each download checked against its published checksums.package:windowsonly packages a runtime staged earlier (--runtime <dir>names another one, on the same drive as the checkout). It builds an NSIS installer intoapps/desktop/src-tauri/target/release/bundle/nsis/. Where WebView2 is missing, the installer runs Microsoft's bootstrapper, which needs the internet at that moment. WebView2 ships with Windows 11 and most Windows 10 installs.
Linux
Gentle Dot ships as a self-contained package: it carries its own Node.js, assistant engine, and Engram, so nothing else needs to be installed first. Pick the file for your system (dpkg --print-architecture or uname -m tells which):
| System | File | Install |
|---|---|---|
| Debian 12+, Ubuntu 24.04+ (x86_64) | gentle-dot_<version>_amd64.deb |
sudo apt install ./gentle-dot_<version>_amd64.deb |
| Debian 12+, Ubuntu 24.04+ (ARM64) | gentle-dot_<version>_arm64.deb |
sudo apt install ./gentle-dot_<version>_arm64.deb |
| Arch Linux, Omarchy (x86_64) | gentle-dot-<version>-1-x86_64.pkg.tar.zst |
sudo pacman -U gentle-dot-<version>-1-x86_64.pkg.tar.zst |
Keep the ./ with apt. The package manager adds WebKitGTK and tray support. Then open Gentle Dot from your app menu, or run gentle-dot.
- The app is
/usr/bin/gentle-dot; its bundled runtime is in/usr/lib/Gentle Dot/runtime. Your data lives in~/.gentle-dot. - First launch needs the network once: the engine installs its companion packages (about 20 seconds).
- Computer control is macOS only.
- Connector secrets (tokens and sign-ins) are kept in your desktop keyring through the Secret Service (GNOME Keyring or KWallet), encrypted on disk, never in
~/.gentle-dot. In Passwords and Keys (Seahorse) they show as "Gentle Dot connector: …" in the login keyring. Connector approvals and connector changes go through the app's own dialogs, which the assistant cannot answer. - Limit on Linux: while the keyring is unlocked (usually your whole session), any program running as your user can read those items, including commands the assistant runs in its shell (for example
secret-tool lookup service dev.gentleman.gentle-dot.connectors account <id>). The Secret Service has no way to restrict which program reads an item. On macOS the Keychain lets only the signed app read them without asking; on Linux, protect the secrets by keeping the keyring locked when you are away and by connecting only the accounts you want the assistant to use. - Without a keyring (no Secret Service in the session, common on minimal window-manager setups), connectors that need a secret do not run, and nothing is written to disk instead.
~/.gentle-dot/daemon.logthen saysno Secret Service in this desktop session (…); install and unlock a keyring such as GNOME Keyring or KWallet. Installgnome-keyring(or KWallet), make sure it runs and is unlocked in your session, then quit Gentle Dot from the tray and open it again. Gentle Dot checks its connectors with a key kept in the keyring when it starts, so a keyring that was missing then keeps those connectors locked, and the assistant says to restart, until the next start. If the keyring goes away while Gentle Dot runs, the assistant says the keyring is missing. A locked keyring shows its unlock prompt when Gentle Dot starts or a connector needs a secret; dismissing it, or no answer within two minutes, refuses (dismissed at start, connectors that need a secret stay locked until Gentle Dot restarts). - GNOME: add a custom shortcut that runs
/usr/bin/gentle-dot --toggle(see docs/linux-testing.md, step 9). Debian needs the AppIndicator extension for the tray icon. - Hyprland / Omarchy: paste
scripts/linux/hyprland/gentle-dot.lua(or.conf) into your Hyprland config; it already calls/usr/bin/gentle-dot --toggle. - Remove:
sudo apt remove gentle-dotorsudo pacman -R gentle-dot(your data in~/.gentle-dotstays). - Build the packages (needs Docker):
pnpm package:linux --arch <arm64|amd64>(amd64 also builds the Arch package); check them in clean containers withpnpm package:linux:check --arch <arm64|amd64>.node scripts/package/linux-cargo-check.mjs --arch <arm64|amd64>runs the desktop crate's tests and clippy on Linux, the keyring store against a real GNOME Keyring on a private session bus, and the app channel checks. - Developers can still build from source with
scripts/linux/setup-debian.shorscripts/linux/setup-arch.sh(app at~/.local/bin/gentle-dot).