Installing Knot
How to install Knot on macOS and Debian/Ubuntu, from download to first synced save. There is no Windows build yet (section 03).
macOS · Linux · Windows · Verify a download · First save
macOS
1. Download
Get the disk image from the latest release (also on the download page). Checking the checksum first is optional: steps below.
2. Install
Open the .dmg, read the bundled INSTALL.txt, and drag Knot into Applications.
3. First open: the one-time Gatekeeper step
Knot is signed but not yet Apple-notarized, so macOS blocks the first open. The xattr command removes the quarantine flag before the first open. The Open Anyway button in System Settings only shows up after macOS has blocked Knot once. Clear it once, any of these ways:
Most reliable, any macOS version
xattr -dr com.apple.quarantine "/Applications/Knot.app"- Or: open Knot once (it gets blocked), then System Settings → Privacy & Security → "Open Anyway".
- Older macOS (pre-Sequoia): right-click Knot → Open → Open.
4. First run
Open Knot. The three-step welcome shows your new device identity (no account, no password: an Ed25519 key generated on your machine) and ends on Protect a folder. Pick any folder; every save in it becomes a real git commit. The daemon starts automatically with the app and keeps running in the background.
+ Updating · uninstalling · where things live
Update: download the new .dmg and drag Knot to Applications again, replacing the old copy. Your projects, identity, and pairings are untouched: they live outside the app bundle.
Uninstall: quit Knot, delete /Applications/Knot.app. Your repositories stay where they are, as plain folders with git history that any git tool can read.
Data locations: identity and settings under ~/Library/Application Support/knot/; your code stays exactly where your folders are.
Linux (Debian / Ubuntu)
1. Download
Get the package from the latest release, then optionally verify the checksum.
2. Install (one command)
sudo apt install ./knot-vcs-amd64.debThe leading ./ tells apt this is a local file; apt resolves the git dependency for you. Double-clicking the .deb will not install it. Current Ubuntu has no GUI that installs local .deb files. App Center is snap-only, and that affects every vendor's .deb.
3. Start the daemon
systemctl --user daemon-reload
systemctl --user enable --now knot-vcsThe package registers the service for every user; this turns it on for yours, now and on every login.
4. First run
Launch Knot from your app launcher (or run knot-app). The same three-step welcome as macOS. Or, from a terminal in any folder:
knot soloturns on watch + auto-commit + sync for that folder.
+ Updating · uninstalling · health check · other distros
Update: download the newer .deb and run sudo apt install ./… again. apt upgrades in place; your daemon, projects, and pairings carry over.
Uninstall: sudo apt remove knot-vcs. The package owns nothing inside your project folders; each one is still a git repository afterwards, readable with plain git.
Health check: knot doctor.
✓ daemon reachable
⚠ Tor onion not published yet (still bootstrapping, or started without --tor)
○ no LAN detected (Tor-only)Each line is a separate check. On a healthy machine you only see the first one. The Tor warning is normal in the first minutes after a cold start.
Other distros (Fedora, Arch, …): not packaged yet. The .deb is the only Linux artifact today; a snap/flatpak is under consideration. If you need Knot on another distro now, say which one.
Windows
Not yet available. Since September 2026 the command line and the daemon build and run on Windows 11, and Tor starts there. What has not happened yet is a commit travelling from a Windows machine to another one, which is the check the macOS and Linux builds each passed, on the MacBook and on the HP EliteBook, before release. When Windows passes it, the download will appear here and in the changelog. The desktop app does not run on Windows yet.
Verify your download
Every release publishes its SHA-256 checksums. Comparing takes one command and proves the file you hold is byte-for-byte the file in the release.
macOS
shasum -a 256 ~/Downloads/Knot-macos.dmgLinux
sha256sum ~/Downloads/knot-vcs-amd64.debThere is no CI: these builds are compiled on one laptop and uploaded to GitHub Releases by hand.
Check that it worked
- Protect a folder (the welcome's last step, or knot solo in a terminal).
- Open any file in that folder, in any editor. Change something. Hit save.
- Watch the dashboard. A debounce runs first, so it is not instant. What lands is a real commit signed by your device identity, and plain git log can read it.
To sync with a second machine: install Knot there too, then pair the two with a one-time code from the Devices tab. After that the saves cross on their own: on a shared LAN the two machines talk straight to each other, while over Tor it is a lot slower. On both routes the bytes are Noise-encrypted and each side checks the other's Ed25519 key before anything moves. When both sides edited and the histories diverged, Knot merges them itself. The merge commit is built deterministically, from sorted parents and a fixed identity, so both machines arrive at the same commit id. It stops if the same lines changed on both sides, or if the incoming side would overwrite edits you have not committed. The push says push refused: not a fast-forward, the other side waits under refs/knot-incoming/, and knot incoming shows you what is parked.