Installing Knot
Everything from download to your first synced save, per operating system. Ten minutes, no account, and your code never leaves your machines.
macOS · Linux · Windows · Verify a download · First save
macOS
1. Download
Get the disk image from the latest release (also on the download page). Verifying the checksum first is optional but takes ten seconds — steps below.
2. Install
Open the .dmg, read the bundled INSTALL.txt, and drag Knot into Applications. That is the whole install.
3. First open — the one-time Gatekeeper step
Knot is signed but not yet Apple-notarized, so macOS blocks the very first open. 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. A three-step welcome walks you through what Knot does, shows the device identity it just created (no account, no password — an Ed25519 key generated on your machine), and ends on Protect a folder. Pick any folder; from that moment 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 — they are plain folders with real git history, readable by any git tool, with or without Knot.
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. Why not double-click? Current Ubuntu ships no GUI that installs local .deb files — App Center is snap-only by design, and this affects every vendor's .deb, not just Knot. One honest command beats a broken double-click.
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: what Knot does → your device identity → protect your first folder. Prefer the terminal? In any folder:
knot soloturns on watch + auto-commit + sync for that folder in one go.
+ Updating · uninstalling · health check · other distros
Update: download the newer .deb and run the same sudo apt install ./… — apt upgrades in place; your daemon, projects, and pairings carry over.
Uninstall: sudo apt remove knot-vcs. Your repositories remain — plain folders with real git history.
Health check: knot doctor diagnoses the daemon, service, and pairing state and names what is wrong in plain language.
Other distros (Fedora, Arch, …): not packaged yet. The .deb is the only Linux artifact today; a store-grade snap/flatpak is under consideration. If you need Knot on another distro now, tell us which — real demand moves it up the list.
Windows
Not yet available. A Windows build is in development and has not been through the same on-real-hardware verification the macOS and Linux builds get before release — and Knot does not ship what it has not verified. When it passes, it lands here and on the changelog first.
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 we shipped.
macOS
shasum -a 256 ~/Downloads/Knot-macos.dmgLinux
sha256sum ~/Downloads/knot-vcs-amd64.debAfter installing: the ten-second proof
- Protect a folder (the welcome's last step, or the Protect a folder button, or knot solo in a terminal).
- Open any file in that folder, in any editor. Change something. Hit save.
- Watch the dashboard: within a few seconds your save appears as a real commit — signed by your device identity, visible to plain git log.
To sync with a second machine: install Knot there the same way, then pair the two with a one-time code from the Devices tab. From then on, saves cross between them automatically — over your LAN when you share one, over Tor when you don't, encrypted end-to-end either way. Merge of histories that diverged while both sides edited is still a manual git merge today; Knot refuses loudly instead of guessing.