Running EtherPK on your own computer

You can run the EtherPK Client entirely on your own machine. Nothing is installed, no account is required, and your notes stay in a folder you choose. This page covers the check to do first, the steps to run it, and what to do when something in a managed workplace gets in the way.

If you only want your notes in a folder and you are happy using the hosted Client, you do not need any of this - see Your Notes In Your Own Folder. Running your own copy is for working offline, for keeping everything on machines you control, or for a workplace where the hosted Client is not an option.

Check your browser first - two minutes

EtherPK opens a folder on your computer through a browser feature called the File System Access API. Only Chromium-based desktop browsers have it: Chrome, Edge, Brave and similar, on Windows, macOS and Linux. Firefox and Safari do not, and neither does anything on iPhone or iPad.

That matters more than usual here, because a managed work computer can have the feature switched off by policy even in Chrome. Check before you spend time on the rest of this page.

The quick test. Open the browser you intend to use, press F12 (or Cmd+Option+I on a Mac) to open developer tools, click Console, type this and press Enter:

window.showDirectoryPicker()

Checking for a workplace policy. If your computer is managed by an employer, open a new tab and go to chrome://policy (or edge://policy on Edge). Use Ctrl+F to search the page for FileSystem. Policies named DefaultFileSystemReadGuardSetting, DefaultFileSystemWriteGuardSetting, FileSystemReadBlockedForUrls or FileSystemWriteBlockedForUrls control this feature. If one is listed and set to block, EtherPK cannot open a folder in that browser and only your IT team can change it. This is a deliberate setting: the same feature that lets EtherPK save your notes could let another site read your documents, so some organisations turn it off across the board.

If the folder route is closed to you, EtherPK still works with a synced graph against a Sync Server

What you need

The bundle is plain JavaScript. There is nothing to install, no administrator rights are needed, and the same download works on Windows, macOS and Linux, on both Intel and ARM machines.

Getting the bundle

The bundle is built by CI for every commit on main. Until it is published somewhere permanent, download it from the build itself:

  1. Open the repository's Actions tab and choose the Build and Push workflow.
  2. Pick a completed run on main whose Standalone Client Node bundle job succeeded.
  3. Scroll to Artifacts and download etherpk-node.

Artifacts are kept for 30 days, so a run older than that will have nothing attached - use a more recent one. This needs an account with access to the repository. If someone has sent you a .tar.gz directly, start at step 2 below.

Unpacking it

The download is wrapped twice: GitHub puts every artifact in a zip of its own, and the bundle inside it is a .tar.gz. So there are two steps, not one.

Unpack it wherever you like - the commands below use C:\etherpk on Windows and ~/etherpk on macOS and Linux, but Downloads is fine too.

One thing to know if you are on Windows: each archive expands into a folder named after itself, so you end up two folders deep before reaching the application. Windows also refuses paths longer than 260 characters. The bundle is built to stay well inside that from an ordinary Downloads path, but if you are already working somewhere deeply nested, unpack to C:\etherpk and the question does not arise.

Step 1 - unzip the artifact. This gives you etherpk-client-<commit>.tar.gz, where <commit> is a short code identifying the build.

On Windows PowerShell:

Expand-Archive -Path "$HOME\Downloads\etherpk-node.zip" -DestinationPath C:\etherpk

On macOS or Linux:

mkdir -p ~/etherpk && unzip ~/Downloads/etherpk-node.zip -d ~/etherpk

Double-clicking the file in File Explorer or Finder does the same thing.

Step 2 - unpack the tarball. This is the one that produces the application.

On Windows PowerShell (tar is built into Windows 10 and 11 - you do not need to install anything):

cd C:\etherpk
tar -xf etherpk-client-*.tar.gz

On macOS or Linux:

cd ~/etherpk
tar -xzf etherpk-client-*.tar.gz

Check you have the right thing. You should now have a folder called etherpk-client containing exactly three items:

etherpk-client/
  build/
  node_modules/
  package.json

All three must stay together in the same folder. If package.json is missing or you moved build somewhere on its own, EtherPK will not start - see the troubleshooting section at the end.

You can delete the .zip and .tar.gz once this folder exists.

Run it

1. Open a terminal in the etherpk-client folder you unpacked above - the one holding build, node_modules and package.json.

On Windows, Shift+right-click the folder and choose Open PowerShell window here. On macOS, right-click it and choose New Terminal at Folder. On Linux, most file managers offer Open in Terminal.

2. Start it.

On macOS or Linux:

HOST=127.0.0.1 PORT=3000 node build

On Windows PowerShell:

$env:HOST="127.0.0.1"; $env:PORT="3000"; node build

You should see:

Listening on http://127.0.0.1:3000

3. Open http://127.0.0.1:3000 in Chrome or Edge. Go to Knowledge graphs, choose Open folder, and pick where your notes should live. From here everything works as Your Notes In Your Own Folder describes.

4. To stop it, press Ctrl+C in the terminal. Your notes are files in your folder and are unaffected.

Why HOST=127.0.0.1

127.0.0.1 is your own computer and nothing else. Without it EtherPK listens on every network connection the machine has, which means two things you probably do not want: other devices on the same network could reach it, and Windows shows a firewall prompt on first run that needs an administrator to approve. Binding to 127.0.0.1 avoids both.

It also keeps the folder feature working. Browsers only allow it on a secure page, which means HTTPS or an address on your own machine. http://127.0.0.1:3000 qualifies; http://192.168.1.20:3000 does not, so sharing your copy across the network would quietly break the very thing you started it for.

Keep the same port

Use the same port every time. Your browser treats http://127.0.0.1:3000 and http://127.0.0.1:3001 as two unrelated sites, each with its own list of graphs and its own search index. Starting on a different port looks alarmingly like your notes have vanished. They have not - your files are untouched - but you will have to pick your folder again. Pick a port and stay on it.

Making it easier to start

Install it as an app - do this one. With EtherPK open in Chrome or Edge, click the install icon at the right-hand end of the address bar, or open the browser menu and choose Install (sometimes under Cast, save and share). This works from your own copy exactly as it does from the hosted one.

Two things change. EtherPK gets its own window with no tabs or address bar, so it behaves like any other application - it appears in your Start menu, Dock or app launcher, and can be pinned there. And, the real benefit, an installed app remembers your folder permission. The once-per-session "Let this site edit files in MyNotes?" prompt described in Your Notes In Your Own Folder stops appearing, so opening EtherPK takes you straight to your notes.

You still need the terminal command running in the background for the window to load - installing changes how EtherPK is presented, not where it comes from. If you have made a shortcut below, start that first, then open the installed app.

One thing it does not yet do is work offline. EtherPK will not start if the local server is not running.

Make a shortcut. Rather than typing the command, save it once.

On Windows, create start-etherpk.cmd next to build containing:

@echo off
set HOST=127.0.0.1
set PORT=3000
node build

On macOS or Linux, create start-etherpk.sh next to build containing:

#!/usr/bin/env bash
cd "$(dirname "$0")"
HOST=127.0.0.1 PORT=3000 node build

then run chmod +x start-etherpk.sh once to make it runnable.

If it does not start

Cannot use import statement outside a module - the package.json from the bundle is missing or was not unpacked alongside build. All three of build, node_modules and package.json must sit in the same folder.

Cannot find module, or a "path too long" error while extracting on Windows - the bundle did not extract completely. A partly extracted bundle is missing files and fails in confusing ways, so delete what was written and extract it again rather than retrying on top of it. If it keeps happening, unpack somewhere shorter such as C:\etherpk.

command not found: node - Node.js is not installed, or is not on your PATH. Check with node --version.

EADDRINUSE - something already uses that port. Choose another and stay on it, remembering that the new port starts with an empty graph list.

It starts, but there is no "Open folder" button - the browser cannot open a local folder. Go back to the check at the top of this page.

On a work computer

Nothing here installs software or needs administrator rights, so it usually runs where locked-down software would not. Three things can still get in the way, and only the last is really about running it:

Where your notes actually are

Running your own copy does not change this: your notes are markdown files in the folder you chose, readable by any editor, and yours to back up or move. The program you just started only serves the application to your browser - it never touches your notes. That work is done by the browser itself, which is why the browser check matters so much and why the folder never needs to be configured anywhere in the command. See Where Your Data Lives for the full picture.