HandshakeBeta

Questions & answers

Everything about Handshake – how it works, where your data lives, and how it compares.

Getting started

What is Handshake?
Handshake is a free, local-first desktop app for mapping the people you know – your network as a graph of people, the connections between them, and the warmth of each tie. It runs on macOS, Windows, and Linux, and stores everything as plain markdown files on your own machine.
How do I get started?
Download Handshake, open it, and create a network – a plain folder anywhere you choose. It seeds your own card at the center of the board; from there, add people by name, set how you met and how warm each tie is, and write notes. Most people have a real map of their inner circle in a few minutes.
Is Handshake free?
Yes. Handshake is free and open source (MIT licensed). There's no account, no subscription, and no paid tier – you download it and it's yours.
Do I need an account or an internet connection?
No. Handshake is local-first and works fully offline. There's no sign-up, no login, and nothing phones home.

Keep reading: the getting-started guide

Privacy & your data

Where is my data stored?
In a folder of plain markdown files on your own device – you pick the location when you create a network. There is no cloud component at all.
Can anyone else read my network?
No. There's no server, no account, and no telemetry – your relationships never leave your machine. Not even we can see them.
How do I back up or sync my network?
Because a network is just a folder of text files, any file-level tool works: git for full version history, or iCloud, Dropbox, OneDrive, or Syncthing for syncing between machines. Handshake also quietly git-versions each network with its built-in Time Machine, so you can snapshot and roll back from inside the app.
What happens to my data if I stop using Handshake?
Nothing bad – you keep a tidy folder of human-readable markdown. Every person, connection, and note stays readable in any text editor, forever. Your data outlives the app.

Keep reading: how networks & plain files work

Platforms & installing

What platforms does Handshake support?
macOS (Apple Silicon and Intel), Windows 10/11, and Linux (.AppImage, .deb, and .rpm). It's a native desktop app built on Tauri – small, fast, and instant to start.
Why does macOS or Windows warn me when I install it?
Handshake isn't code-signed yet (it's in public beta), so macOS Gatekeeper and Windows SmartScreen flag it as coming from an unidentified developer. On macOS: right-click the app → Open → Open. On Windows: click More info → Run anyway. The full source code is on GitHub if you'd like to check it first.
The window is blank on Linux (Hyprland / sway) – what do I do?
On some Wayland compositors, WebKitGTK's DMABUF renderer hits a protocol error and renders nothing. Launch Handshake with the renderer disabled: WEBKIT_DISABLE_DMABUF_RENDERER=1 handshake. Putting that env var in your launcher or a small wrapper script fixes it permanently.
How do updates work?
New releases ship on GitHub with installers for every platform. During the beta, you update by downloading the latest release – each version's notes say what changed.

Keep reading: the download page

Files & format

What file format does Handshake use?
Plain markdown (.md) files with YAML frontmatter, organized in a simple folder structure: people/, handshakes/, goals/, interactions/, and attachments/. No database, no proprietary format.
Can I open my network in Obsidian?
Yes – a Handshake network is a valid Obsidian vault. Open the same folder in Obsidian and every person and note is right there as markdown. Edits you make outside Handshake flow back in when you return.
What are backlinks?
Type [[ in anyone's note and Handshake autocompletes from your people. Mentioning someone – like [[Sarah Chen]] – draws a dotted connection on the board and makes their card grow with inbound mentions. Your notes quietly become a navigable map.

Keep reading: the plain-files guide

Compared to other tools

How is Handshake different from a CRM?
A CRM is built for sales pipelines: deals, stages, follow-up automation, in the cloud. Handshake is a personal thinking tool for the people in your life – who they are, how you met, who connects to whom – stored privately as files you own. No pipeline, no quota, no server.
How is Handshake different from Obsidian?
They share a philosophy – local-first, plain markdown, links between notes – which is why we call Handshake 'Obsidian for your network.' The difference is specialization: Obsidian is a general knowledge base, while Handshake is purpose-built for people – a spatial board of warmth-weighted ties, person cards with photos and roles, goals, and introduction paths.
Why not just use a spreadsheet?
A spreadsheet stores rows; it can't show you the shape of your network. Handshake lays everyone out spatially, draws the ties between them, fades the connections going stale, and lets you write real notes on every person – while staying just as portable, because it's all plain text underneath.

Keep reading: the honest guide to personal CRMs

Beta

What does 'public beta' mean for Handshake?
Handshake is pre-1.0: the core is complete and stable enough to live in daily, but it's still evolving fast and releases aren't code-signed yet. Your data is safe regardless – it's plain files, and the built-in Time Machine keeps versioned snapshots.
How do I report a bug or request a feature?
Open an issue on GitHub. For bugs, Handshake has a built-in debug report – press Ctrl-Shift-D in the app and attach the generated report (it can redact your vault path and platform); it makes most bugs quickly diagnosable.

Keep reading: the changelog

Something else on your mind? Ask on GitHub.