Servers and signing in
Nether works without a server: a vault is a folder of Markdown files on your computer. A Nether server, which you or your organization runs, adds sync between devices, sharing and collaboration. The app signs in to it first.
Connecting to a server
Section titled “Connecting to a server”Run Servers and signing in from the command palette (Ctrl+P, or Cmd+P on
macOS), and type the server’s address, such as nether.example.org. Nether
uses https:// unless the address says otherwise. The server tells the app
how you may sign in:
- Password: your email address and the password of your account.
- Email me a code: the server emails you a code of eight digits, which works once, within 15 minutes. It appears when the server’s admin has set up email.
- Sign in with …: your organization’s single sign-on, such as Keycloak, Okta or Microsoft Entra ID, one button for each provider the server’s admin has set up. The app opens it in your browser; once you have signed in there, the browser comes back to the app, and you can close the page it shows.
Accounts come by invitation from a workspace’s owner or admin, so ask them for one if the server says it has none for you.
Setting up a new server
Section titled “Setting up a new server”A server just started has no account. Connecting to it, or opening its web app and choosing Sign in, asks for its setup code instead of a password: the server writes it to its log each time it starts, after “Set it up from the app with this code”. Type it with your name, email address and password, and the name of the first workspace. You become the server’s admin, signed in, and can invite the others. The code works once, and only someone who can read the server’s log has it.
Where the app keeps your sign-in
Section titled “Where the app keeps your sign-in”The app keeps the servers you have signed in to and their accounts in its settings, and each session’s key in your system’s own keychain: the Keychain on macOS, the Credential Manager on Windows, and the Secret Service, as GNOME Keyring or KWallet, on Linux. It is never written to a vault or another file.
A session lasts 30 days without use and 90 days in all; after that, sign in again. Sign out ends the session on the server and removes it from the app; if the server cannot be reached, the app forgets it anyway.
Syncing a vault
Section titled “Syncing a vault”Open the vault, run Sync this vault from the command palette, and choose a server you are signed in to and one of your workspaces. The vault’s notes go to the workspace, and a line at the foot of the sidebar tells how sync is going: synced, notes still to send, or offline, when changes wait on your computer until it is back.
To have the vault on another computer, open an empty folder there as a vault, run Sync this vault, and choose the same workspace: every note comes from the server with its links, properties and history.
A vault syncs with a workspace that has no notes, or into a vault that has none, so no note is ever made twice. Each note’s text merges character by character, so two computers editing one note, even offline, keep both edits, with no conflict to resolve. A note moved or removed on one computer is moved, or sent to the trash, on the other. Stop syncing keeps the notes where they are, on the computer and on the server.
The vault’s other files sync too: images, PDFs, audio, video and the
like, each sent to the server once however many notes or folders have it.
Their bytes cannot merge, so when two computers change the same file
before syncing, both versions are kept: the one the server had first at
its place, and the other beside it, as map 1.png. Hidden folders, such as
.obsidian, stay on each computer. A file larger than the server takes,
100 MB unless its admin sets otherwise, stays on your computer, and the
line at the foot of the sidebar names it.
On a phone
Section titled “On a phone”The Android and iOS apps sign in as the desktop app does: choose Sign
in to a server on their first screen, or run Servers and signing in
from the command palette. A password and an emailed code work as above,
and the code’s field offers the one from Mail or Messages. A provider,
and single sign-on, opens in the system’s sign-in sheet on iOS, or a
browser tab on Android, and comes back to the app by its own address,
io.github.fzn0x.nether:/sign-in/provider, which every server accepts:
admins register nothing new.
Each session’s key is kept in the iPhone’s Keychain, on that phone only and never in iCloud, or on Android sealed under a key from the phone’s Keystore. Backups leave it out, so a phone restored from one signs in again.
The first screen lists the workspaces of each account you are signed in to. Tap one to open it as a new vault on the phone, which the workspace fills as it syncs. Sync this vault links a vault already on the phone instead, as on a computer.
A phone syncs while Nether is on screen. As you leave it, the app saves every open note and sends what it can in the time the system gives; as you come back, or when the network returns, it catches up at once. Edits made offline wait on the phone until then. Servers must use HTTPS: only a debug build reaches plain HTTP, on the emulator’s host, for development. Webhooks and API tokens are managed from a computer.
The web app
Section titled “The web app”A Nether server is also a web app: open its address in a browser, such as
https://nether.example.org, and sign in there. Each workspace of yours is
listed, and opens as a vault in the browser, which keeps a copy of it and
syncs it as the desktop app does. Make a new workspace from the same page.
- Offline. Once opened, the app and the workspaces it keeps open with no connection; changes wait, and sync when the server can be reached.
- As an app. The browser’s install button, in its address bar or menu, installs Nether as an app of its own window.
- One tab per workspace. A workspace opens in one tab of a browser at a time; another tab says it is open already.
- Files. Exports download, PDFs through the browser’s print dialog, and imports come from the browser’s file and folder pickers. Previews of web links need the desktop app.
- Signing in. Invitation links and the links in sign-in emails open the web app. Account and encryption signs out, and turns on or unlocks end-to-end encryption.
- On a phone. One note shows at a time, under a bar: its menu button opens your notes and the menus as a drawer, beside the buttons for Open a note and the command palette. Menus and dialogs open from the bottom of the screen. While you write, a bar over the keyboard inserts blocks and links, makes text bold, italic or code, makes and indents lists, moves, duplicates or deletes the block you are in, and undoes. A property moves up or down from the menu its handle opens.
What a browser keeps goes when its site data is cleared; what has synced stays on the server.
Members and invitations
Section titled “Members and invitations”Workspace members, in the command palette, lists the people in the workspace the vault syncs with, and each one’s role:
- Owners do everything, including making other owners and admins. A workspace always keeps one whose account is active.
- Admins invite people and change or remove members and guests.
- Members read and write every note.
- Guests open only the pages shared with them, at the level they are given there. A guest who edits a page adds its images and files too.
To invite someone, owners and admins choose their role and, if only they should be able to accept, their email address, then Make an invitation link. Send them the link: it works once, for 7 days, and Withdraw stops it sooner.
To join with a link you were sent, open Servers and signing in, choose Join with an invitation and paste it. You see which workspace and role it is for, then join with the account this computer is signed in to on that server, or make one there. Then open an empty folder as a vault, and Sync this vault with the workspace to fetch its notes.
Leave the workspace takes you out of it. The vault keeps its notes and stops syncing.
Someone your organization’s directory has deactivated shows as Deactivated. They sign in no way until it turns them back on, and keep their place and role meanwhile, so they come back as they were.
Someone a group of the directory’s gives a place shows Through the group. Owners may raise them above the group’s role, but not lower them below it or remove them, and they cannot leave: the directory changes their groups.
Editing together
Section titled “Editing together”When others have a note open that you have open too, each edit reaches everyone as it is made. Their carets show in the note, each a line in a color of their own with their name above it, and the text they select is tinted the same. Your name is your account’s on the server.
In an encrypted workspace, edits come a few seconds apart, as they do for notes no one has open, and no carets show yet.
Comments
Section titled “Comments”In a vault that syncs with a workspace, you can comment on a note’s text:
- Select the text and press Ctrl+Alt+M (Cmd+Option+M on a Mac), or run Comment on the selection from the command palette. With nothing selected, the comment is on the block the caret is in. A block’s menu, beside it, has Comment too.
- Write the comment in the box that opens in the Comments panel beside the note, then click Comment or press Ctrl+Enter.
- The text commented on is tinted in the note. Click it to show its thread, or click a thread’s quote to show its text in the note.
- Reply to a thread from its box, and Resolve it once it is settled: it folds away under Resolved, where Reopen brings it back. You can edit and delete your own comments.
A thread follows its text as anyone edits the note. If that text is deleted, the thread stays on its block. Comments sync with the note, even when you comment offline, and in an encrypted workspace they are encrypted too. They are not in the note’s Markdown file, which holds only the note. Those who Can comment on a space or page comment on its notes without changing them; those who Can view read the comments.
Mentions and notifications
Section titled “Mentions and notifications”Type @ in a comment to mention someone in the workspace: a word of their name narrows the list, and the arrow keys and Enter, or a click, pick them. They are told in Nether, and by email when the server sends email. Only those who may open the note are told. A mention made offline is sent once you are back online.
Notifications, at the foot of the sidebar or in the command palette, lists who mentioned you and where, the new ones marked. Choose one to open its note and thread, or Mark all as read. Clear Email me when someone mentions me there to get no more emails. In an encrypted workspace, a notification and its email say only who mentioned you, and in which workspace.
Spaces and sharing
Section titled “Spaces and sharing”A workspace’s notes are in spaces, which Spaces, in the command palette, lists:
- General holds every note in no other space, and every member opens it.
- A teamspace is a folder at the top of the vault, opened by the members its makers add, each with Full access, Can edit, Can comment or Can view. Naming a new teamspace after a folder you have makes that folder the teamspace’s: its notes leave General, and only the teamspace’s members still open them. Those with full access add and remove its members, rename it, which renames its folder in every member’s vault, and delete it once it is empty.
- Your private space is the
Privatefolder, which only you open.
A note moved into a space’s folder joins that space, and leaves the vaults of those who do not open it.
Share this page, with a note open, shares it on its own, with its subpages, the notes in the folder beside it. A page shared on its own keeps everyone who opens the space it is in, unless you choose Only the people below. Those with full access give members access to it, and invite a guest by a link: a guest opens the pages shared with them, and nothing else of the workspace. Stop sharing it on its own puts it back with its space.
Share links
Section titled “Share links”A page shared on its own can also be opened by anyone with its link, with no account. Under Anyone with the link, in its Share this page dialog, choose what the link lets its visitors do, then Make a link, which makes one and copies it; give it a date to expire on, and a password, if you want them.
- Can view opens the page and its subpages to read, with their images.
- Can comment opens them to read, live as they change, and to comment on.
- Can edit opens them to edit, live beside whoever else is in them, and to comment on. A visitor edits the pages’ text, but cannot add, rename, move or delete pages.
The link opens the page in the web app. A visitor who comments or edits gives a name first, which their browser keeps. Their comments carry it, marked (by a link), since no account stands behind it, and an edit link’s visitor’s caret shows it to the others. Whoever opens a link sees nothing else of the workspace, not even other pages’ names. Copy link copies it again, and Revoke stops it, which ends what it opened. A server opens links only when it serves the web app. Its admin may let a workspace’s links only view, or open nothing, by a data policy.
Publishing
Section titled “Publishing”Publish to the web, in the same dialog, publishes the page with its
subpages, or its folder, as a public site the server serves at
/p/<name>/, for anyone, with links only between the site’s pages.
Publishing has the details.
An encrypted workspace has no spaces, shared pages or links yet: everyone in it opens all of it.
End-to-end encryption
Section titled “End-to-end encryption”A workspace can be encrypted, so that only its members’ computers can read its notes: the server keeps them and syncs them, but holds nothing it can read, not even their titles. Encryption is chosen when a workspace is made, and stays.
Turn it on once for your account: in Servers and signing in, choose Turn on end-to-end encryption. Nether shows a recovery phrase of 24 words. Write them down, in order, and keep them somewhere safe: they are the only way to open your encrypted workspaces on a new computer, and no one, not the server’s admin nor Nether’s makers, can recover them for you.
Make an encrypted workspace in Sync this vault: give it a name and choose Make it encrypted, then sync the vault with it.
On another computer, sign in to the server, choose Unlock with the recovery phrase, and type the 24 words. Your encrypted workspaces then sync there as the others do.
Members of an encrypted workspace get its key from another member’s computer, sealed so only theirs can open it, the first time a member who has it opens Nether after they turn encryption on. Until then, their sync waits for it.
The server cannot search an encrypted workspace, publish it, or keep its history; those come from the apps that can read it.
API tokens and webhooks
Section titled “API tokens and webhooks”Scripts and other services reach a server through its REST API, with a personal access token:
- API tokens on a server, under your account in Servers and signing in, or API tokens in the Sync menu, lists your tokens and makes one: what it is for, whether it only reads, which workspace it reaches and when it expires. Making one asks for your password; if you sign in with single sign-on, leave it empty within ten minutes of signing in. The token shows once, to copy. Revoke stops one at once.
- Workspace webhooks, in the Sync menu, are for a workspace’s
owners and admins. A webhook tells another service when a note is made,
changed or deleted. Add one with its
https://address, copy its secret once, then send it a test and read its recent events there.
For admins
Section titled “For admins”The server’s README covers running a server and its first-run setup, email, single sign-on, where attachments are kept, how long history is kept, and every setting.
- Search: the server indexes the notes of workspaces it can read as they are stored, and searches only what each account may open. Encrypted workspaces are searched in the apps.
- Backups: with
NETHER_BACKUPset, the server backs up its database and attachments on a schedule, to a folder or an S3 bucket, and keeps the latest few.node dist/admin.js backupmakes one now,backupslists them, andrestorerestores one into an empty database, at the version it was made with, then brings it up to date. CI restores a backup the same way on every change. - Upgrades: the server brings its database up to date as it starts, and may skip versions.
A self-hosting guide comes with the server’s docker compose setup.