Sync

Your devices hand their notes to each other directly, over your own network. There is no account, no server, and nothing of yours passes through anybody else's machine.

What syncing means here

Two devices that you have introduced to each other exchange what you have written — notes, recordings, edits — straight across the network you are both on. Nobody else is involved. Nothing is uploaded, and there is no service to sign up for, go down, or change its terms.

Every device keeps a full copy. Your phone is not a window onto your desktop; it holds the whole vault, and so does the desktop. Either one on its own is the entire notebook.

Turning it on

Open Settings from the top bar, choose Sync, and turn on Let other devices reach this one. That is the whole of it.

That switch is the only thing in Gilune that opens a port on your machine, and nothing else does it. With sync off, everything else works exactly as it always did — writing, voice capture, transcription, tasks, search — and nothing on the network can reach the app at all. Sync is something you opt into, not something you switch off.

The switch is remembered. Once you have turned it on, Gilune comes back ready to reach your other devices every time it starts, without asking again — you turn it on once, not once per session. Turning it off is remembered just as firmly.

The Windows firewall

Other devices reach Gilune through a Windows Firewall rule, named Gilune, that lets the app answer on private networks and on no other. Private means the network at home or in the office that you already trust; public means the café and the airport, where you do not want the app answering strangers. Gilune only starts listening when you turn sync on — you will never open a port by simply writing a note.

Gilune is installed for your own account, so installing and updating it never asks for an administrator. Adding a firewall rule does, once: the first time you turn sync on, Gilune asks Windows for the rule and Windows asks for an administrator's approval, naming Gilune. Approve it and you are never asked again. The line under the switch says where the rule stands, and offers to ask again if the request was declined. If you are not an administrator, Windows asks for an administrator's password at that moment; with none to hand, say no, and sync simply waits until someone can approve it.

On a work laptop where installing needs an administrator anyway, run the installer as administrator for that first install: it adds the same rule there and then, and Gilune never asks. Updates afterwards need no administrator and keep the rule.

An administrator can also add the rule by hand, in a terminal opened as administrator — replace <you> with your Windows user name:

netsh advfirewall firewall add rule name="Gilune" dir=in action=allow enable=yes profile=private program="C:\Users\<you>\AppData\Local\Programs\Gilune\Gilune.exe"

Gilune installed for all users of a computer, as releases up to 1.2.0 were (under C:\Program Files\Gilune), carries the rule from its installer instead. The next update moves such a copy to your own account; Windows asks once, to remove the all-users copy, and after that updates ask nothing.

A block left behind

Clicking Cancel on Windows's own firewall prompt, or that prompt appearing for someone who is not an administrator, leaves a block rule behind — and a block stops every inbound connection on every network profile, private included, however many allow rules sit beside it. Releases before 1.1.1 listened from the bundled Java runtime, so such a block names runtime\bin\javaw.exe; since then Gilune listens from Gilune.exe itself. The Sync page says so in red beside the switch while a block stands, and its Fix the rule button clears it the same way the first request did — one administrator approval. An administrator can also clear it by hand in a terminal opened as administrator: remove every rule Windows made for the program, then add the one Gilune needs.

netsh advfirewall firewall delete rule name=all program="C:\Users\<you>\AppData\Local\Programs\Gilune\runtime\bin\javaw.exe"
netsh advfirewall firewall delete rule name=all program="C:\Users\<you>\AppData\Local\Programs\Gilune\Gilune.exe"
netsh advfirewall firewall add rule name="Gilune" dir=in action=allow enable=yes profile=private program="C:\Users\<you>\AppData\Local\Programs\Gilune\Gilune.exe"

For a copy installed for all users, the program path is C:\Program Files\Gilune\Gilune.exe (and C:\Program Files\Gilune\runtime\bin\javaw.exe for the older releases) instead.

The same rules are listed under Windows Defender Firewall ▸ Advanced settings ▸ Inbound Rules, where a block row for either program can be deleted by hand instead.

Pairing two devices

Devices only talk to each other after you have introduced them, and you do that once per pair. There are three ways to do it, and they are the same introduction underneath — two of them just save you typing.

From the list of devices on your network

1. Turn sync on, on both devices.
2. On one device, in Settings ▸ Sync, press Start pairing. It shows a six-digit code.
3. On the other device, press Look for devices. The first device appears in the list with its fingerprint; press Pair… on its row, type the six digits it is showing, and press Pair.

That is the whole of it: no address to read off one screen and type into another, because the search just found it. If the row says the device did not answer, check that it is still showing a code — a device that is not showing one gives a stranger no reply at all, by design.

With the six-digit code and an address

1. On one device, in Settings ▸ Sync, press Start pairing. It shows a six-digit code, and the address or addresses that device can be reached at.
2. On the other device, on the same screen, find Enter a code from another device and type in one of those addresses and the code.
3. Press Pair.

This works between any two devices, in either direction, always — including on a network where Look for devices finds nothing. It is the way that never depends on anything else being in place.

When more than one address is offered

A computer can be on several networks at once without knowing it — your own network, and the private ones that virtual machines, containers and VPNs quietly add. It cannot tell which of those your phone is on, so it does not guess: while a pairing code is open it lists every address it is reachable at, best first. The same list appears under This device on the Sync page, whether or not a pairing is open.

Type whichever one belongs to the network the other device is on. The first in the list is the best guess and is usually right; trying another costs nothing — a wrong address simply does not connect, and the code stays good until it expires. Scanning the QR skips the question entirely: the phone is handed every address the code carries and tries them in turn.

A code is good for one pairing only, it expires after a few minutes, and a few wrong tries cancels it. If any of those happen, nothing is broken and nothing is at risk — press New code and start again. A code that could be guessed at forever would not be worth six digits.

With the QR code

While a code is open, the desktop shows the same introduction as a QR square beside the digits. On the phone, open its Sync screen and scan it. That is the whole difference: the same pairing, without typing an address and six digits into a phone.

The QR goes one way — the desktop shows it, the phone reads it. Two desktops pair with the code.

Making sure you paired with the right device

Under This device, each device shows a short fingerprint of its own: a handful of letters and digits, the same every time. After pairing, each device lists the other one with the fingerprint it saw during the introduction.

To check, put the two screens side by side: the fingerprint your desktop lists for the phone should be character-for-character the fingerprint the phone shows for itself, and the other way round. If they match, you paired with the device you meant to.

Finding devices automatically

Once sync is on, a device announces itself on the network it is connected to. Press Look for devices on the Sync page and everything that answers appears in a list — the ones you have already paired with, and any you have not. A device you have not paired with can be paired straight from its row, with the code it is showing.

Syncing uses this on its own, too. Gilune tries the address it already has for a device first, because that is by far the quicker of the two; only when that address no longer works does it go looking. So a device that has moved to a different address usually just works again, without you doing anything.

What gets announced is deliberately anonymous: a short fingerprint, and nothing else. Not the device's name, not the name of your vault, nothing about you and nothing about what you have written. Anyone else on the same network can tell that a Gilune device is there — that is true of anything that announces itself — but not whose it is or what it is called.

The name you actually see beside a device turns up only after the two of you have paired. Names are exchanged privately, between devices that already know each other.

What syncs

Everything in the vault, both ways. Every note, however it was made — in Gilune, in Obsidian, with New note, or copied in as a file — every recording, every image or other file you put in a vault folder, and every edit you make on either side. Deletions travel too — delete a note on the phone and it goes from the desktop as well. Folders travel with what is in them; an empty folder stays where it was made.

A note Gilune did not write gets a short block of properties at the top the first time Gilune sees it — its id and a few gilune- lines. That is how the two devices know they are looking at the same note after it has been renamed or edited on both. Your own text and your own properties are kept exactly as they were. Other files are never written into: an image is carried as it is.

Keeping something on one device

On the desktop, while sync is switched on for the vault, right-click a note or a folder in the files list: the menu carries Sync this note or Sync this folder with a small switch — on means it syncs, off means it stays on this device. Switch a folder off and everything inside it stays too; the rows inside then show Kept here by a folder above, because the folder decides for them. A note's own ⋯ menu carries the same switch. A note or folder that is kept local shows local beside its name in the list.

Underneath, those are two marks you can also write yourself, and either works on its own. Add gilune-sync: local to a note's properties, and that note stays where it is. Put an empty file named .gilune-local in a folder, and everything in that folder and below it stays. A local note is still searchable and still yours; it simply never leaves. Take the property off, or delete the marker file, and the note joins the others on the next sync. A note that had already synced before you made it local stops being sent, and your other devices keep the copy they had.

If the same filename is created on two devices before they sync, both are kept: the one that arrives is saved beside yours with the other device's short id in its name, so you can merge them by hand.

A note sometimes arrives a little before its recording does: the words are small and the audio is not, so the audio follows on behind. That is normal, and nothing is missing — the note fills in when the recording lands.

When it happens

The desktop listens the whole time the app is open, so anything another device sends arrives while you are working. If you want to push what you have just written without waiting, press Sync with devices now at the bottom of the Sync page. While it runs, the line under the button says which device is being contacted and how — reaching a device that has gone quiet takes a few seconds per step — and when it finishes, a Last sync box under the button says what happened with each device: what was received and sent, or why one could not be reached. A device that cannot be reached does not hold the others up.

The phone syncs when you open it, and again every time you come back to it. On top of that it checks in the background roughly every fifteen minutes, on Wi-Fi, when the battery is not low.

Revoking a device

Beside each paired device is a Revoke button, and either device can do it to the other. It takes effect immediately: the device can no longer connect, and an exchange happening at that moment stops there and then.

A copied vault becomes a new device

Copy your vault folder to another machine, or restore it from a backup, and Gilune treats that machine as a new device with a history of its own. This is deliberate: two machines writing as though they were the same device would tread on each other's history, and the notes would be the thing that suffered.

It is also why one vault can end up showing two devices in the list. Gilune says so plainly on the Sync page when it happens, the original device is unaffected, and you can revoke whichever one you did not mean to have.

Starting again after a restored backup (phone)

Each device proves which device it is with a key that its phone or its computer keeps for it, locked away outside your vault. That key does not travel: restore a backup onto a new phone, reset the phone's secure storage, or move the app to another handset, and the proof comes across but the thing that unlocks it does not.

When that happens the phone's Sync page says so in as many words, and offers Reset sync on this phone. This button is on the phone only — a desktop in the same state tells you what is wrong on its own Sync page, and its identity is rebuilt by pairing again from scratch.

Pressing it throws away the identity this phone holds, its list of paired devices and its on-or-off setting, and enrols the phone afresh. It touches nothing in your vault: every note, recording and edit is exactly where it was. Your other devices will not recognise this phone afterwards, so pair each of them again — a new introduction, not an undo.

When something is not working

• Nothing is found at all. Many guest, hotel and office networks deliberately stop the devices on them from seeing one another. On a network like that, no amount of waiting will help and there is nothing wrong with Gilune. Put both devices on a network of your own, or turn on the phone's hotspot and use that. Check the found by others line under This device on each machine, too: a device announces itself only when that says so, and a desktop that says it is not findable can be restarted to try again.
• A device is found but will not connect. It is on, it is on your network, and everything sent to it is being dropped. On a Windows machine the usual cause is that Windows has classed that network as Public — it does this for every new network, and a Wi-Fi extender's name counts as a new network — so the firewall rule that allows Gilune on private networks does not apply there. On that machine, open Settings ▸ Network & internet, open the network's properties and set it to Private. The Sync page on that machine says so itself, in red beside the switch, whenever Windows is treating one of its networks as Public. Failing that, check that sync is switched on over there and that Gilune was allowed through its firewall. Syncing from the affected machine to the others works throughout: it is only the connections others open to it that are dropped.
• It used to work and now it does not. The other device's address has probably changed — routers hand out new ones from time to time. Read the current address off that device's Sync settings and type it into the address field on this one.
• A message says something is being held back. Gilune stops rather than accept something it cannot make sense of or verify, and it tells you what it was and why. Nothing is lost by this: once the problem clears, it picks up exactly where it left off.

Messages that are not a problem

Some of what the Sync page tells you is simply news. These are the ones that sound like faults and are not — nothing has stopped, and there is nothing to fix.

• A change referred to something from a device you removed. It was set aside, and nothing is lost. Something arrived that was about a device you have revoked — an edit to one of its notes, say — so there was nothing left for it to be about. What that device sent you before you revoked it stays in your vault, and everything else carries on as normal.
• A file is too large to carry. Files over 512 MB stay on the device they are on and are not synced. Nothing is wrong with the file.
• A file arrived and found another at its path. It was saved beside the existing one, named for the device it came from. Both are kept.
• A note's text file could not be read. Gilune left the note alone rather than rewriting it with a gap where the words should be. If you moved or renamed the file with another app, put it back and it reappears. Nothing was lost: Gilune's own record of the note is untouched, and the rest of your vault is unaffected.
• Something from another device is waiting for the rest of its history. Two devices met in the wrong order, which happens. It sorts itself out at the next sync without anybody doing anything.
• Something a newer version wrote came through. This device kept it exactly as it arrived and passed it on to your other devices unread. Nothing is lost; it becomes readable here when this device is running that version too.