Running EtherPK On Your Own Computer

You can run EtherPK on your own computer instead of using it at app.etherpk.com. Your copy is the same app, served to your browser by a Node.js program on the same computer. It comes as a Node bundle or a Docker image. Both are free, and neither needs an account. The Node bundle is an archive of program files that you start with Node.js, with no installer and no administrator rights.

The program sends the app to your browser and never reads or writes your notes. You open your notes folder in the browser itself, and the browser reads and writes the Markdown files in it. That is why the start command names no folder, and why your notes stay in the folder after the program stops.

Your copy opens local graphs, which are sets of notes kept as Markdown files in a folder on your computer. See Local Graphs for more information. For Synced Graphs, go to app.etherpk.com instead, because Managed Sync needs EtherPK sign-in settings that your copy does not have.

Your browser alone decides whether you can open a folder, so check it before you download anything. You need Chrome or Edge on a computer, a secure address (127.0.0.1, localhost or HTTPS), and no workplace browser policy that switches folder access off. The browser also keeps a separate graph list for each address, so start your copy on the same address and port every time.

By default, your copy uses EtherPK services for spell check dictionaries, map tiles, postcodes and the Extension Directory. Each one has its own setting that points it at another service or turns it off.

Before you begin

Node.js 24 or later. Check your version with node --version in a terminal.
Chrome or Edge on a computer. The browser must pass the folder access check below.

Check folder access in the browser

This check makes the same call that EtherPK makes to open a folder, so it tells you whether EtherPK can open one. Run it in the browser you will use, on any page whose address starts with https://.

In the browser, open the developer tools and select the Console tab.

Type this line and press Enter:

window.showDirectoryPicker({ mode: 'readwrite' })

If a folder picker opens, EtherPK can open a folder in this browser.

If you get an error saying that showDirectoryPicker is not a function (the wording varies from browser to browser), the browser cannot open a folder. EtherPK does not show the Open folder (Local Graph) button in it, so switch to Chrome or Edge. See Choosing Where To Store Your Notes for more information.

On a computer your employer manages, a workplace policy can switch off folder access in Chrome or Edge, and only your organisation can change it. To look for one, open chrome://policy (edge://policy in Edge) and check for these policies:

DefaultFileSystemReadGuardSetting
DefaultFileSystemWriteGuardSetting
FileSystemReadBlockedForUrls
FileSystemWriteBlockedForUrls

If a policy blocks folders, you can use a synced graph at app.etherpk.com instead. A synced graph works in any browser and needs an EtherPK account with Sync+.

Download and unpack the bundle

Open the etherpk-client Releases page on GitHub.
Under the newest release, in Assets, download etherpk-client-<version>.tar.gz.

Unpack the file from your Downloads folder. On Windows, run these commands in PowerShell to unpack it into C:\etherpk:

New-Item -ItemType Directory -Force C:\etherpk | Out-Null
tar -xf "$HOME\Downloads\etherpk-client-<version>.tar.gz" -C C:\etherpk

On macOS or Linux, run this command in a terminal to unpack it into ~/etherpk:

mkdir -p ~/etherpk && tar -xzf ~/Downloads/etherpk-client-<version>.tar.gz -C ~/etherpk

This gives you a folder named etherpk-client with build, node_modules and package.json inside. Keep the three together, because the program in build loads its packages from the node_modules folder beside it.

Start EtherPK

In the etherpk-client folder, open PowerShell on Windows or a terminal on macOS or Linux.
Run the start command for your system. In PowerShell, run:
```
$env:HOST="127.0.0.1"; $env:PORT="3000"; node build
```
On macOS or Linux, run:
```
HOST=127.0.0.1 PORT=3000 node build
```
The terminal prints Listening on http://127.0.0.1:3000.
In Chrome or Edge, go to http://127.0.0.1:3000. The EtherPK home page opens.
Select Open The App. The Graphs page opens.
Select Open folder (Local Graph) and choose your notes folder.

EtherPK opens the folder as a local graph named after the folder. When you come back to the same address, it goes straight to that graph, or to the one you opened last if you have several.

To stop EtherPK, press Ctrl+C in the terminal.

Address and port

With HOST=127.0.0.1, only this computer can reach the program. Without HOST, the program listens on every network connection, so other devices on your network can reach it too. They still cannot open a folder, though, because a network address such as http://192.168.1.20:3000 is not secure.

If you switch to another port or host name, even to localhost in place of 127.0.0.1, the Graphs page comes up empty. Your files are unchanged, and picking the folder again opens them.

Start script

On macOS or Linux, you can start EtherPK with a script instead of typing the command. Save this as start-etherpk.sh in the etherpk-client folder, next to build:

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

Run chmod +x start-etherpk.sh once, and from then on you can run the script from any folder.

Installed app

You can install your copy as an app with Install app, just as you can at app.etherpk.com. After your first visit, the browser keeps the files for each version of the app, so you can start the installed app while the program is not running. See Installing EtherPK As An App for more information.

Update EtherPK

The bundle does not update itself. To update it:

Download the newer bundle from the same Releases page.
Stop EtherPK with Ctrl+C.
Remove the old etherpk-client folder.
Unpack the newer bundle in the same place.
Start EtherPK on the same address and port.

Your notes live outside the etherpk-client folder, so removing the folder does not touch them. It does remove any start script you saved inside it.

Settings

Each setting is an environment variable, and you set it the same way as HOST and PORT. The program reads them when it starts, so restart it after you change one. If you leave one of the service settings unset, your copy uses the EtherPK service.

An empty value turns the service off, and your copy does not contact it. To give an empty value, write the name with nothing after the =, as in PUBLIC_DICTIONARY_URL= node build on macOS or Linux or -e PUBLIC_DICTIONARY_URL= with Docker. On Windows, Command Prompt removes a variable set to nothing, and PowerShell might too, so your copy goes on using the EtherPK service.

Setting	When unset	What it sets
`HOST`	`0.0.0.0`, every network connection	The address the program listens on
`PORT`	`3000`	The port the program listens on
`PUBLIC_DICTIONARY_URL`	`https://dictionaries.etherpk.com/v1`	Where the browser downloads dictionaries for Spell Check
`PUBLIC_MAP_STYLE_URL`	`https://maps.etherpk.com/styles/light.json`	The MapLibre style for Maps. When empty, maps show places and routes on a plain background.
`PUBLIC_POSTCODES_URL`	`https://maps.etherpk.com/postcodes`	Where postcode lookups come from
`EXTENSION_DIRECTORY_URL`	EtherPK's directory	The Extension Directory, the list of Extensions you can install. Extensions in EtherPK's directory come from the npm registry.

The etherpk-client .env.example file lists every setting and what each one does, apart from the EtherPK sign-in settings that Managed Sync needs.

Docker image

The Docker image, ghcr.io/appsoftwareltd/etherpk-client, runs the same program as the Node bundle and listens on port 3000 inside the container. This command runs it for this computer only:

docker run --rm -p 127.0.0.1:3000:3000 ghcr.io/appsoftwareltd/etherpk-client:latest

Then go to http://127.0.0.1:3000 in Chrome or Edge. Pass settings with -e NAME=value or --env-file. You open your notes folder in the browser on your computer, not inside the container, so the container needs no folder mount and the same folder access check applies.

Start-up errors

"Cannot find package" or "Cannot find module"

You get one of these errors when node_modules is missing or only partly unpacked, when build has been moved away from it, or when a partly unpacked build is missing a file. Keep build, node_modules and package.json together in the etherpk-client folder, as the bundle unpacks them.

"EADDRINUSE: address already in use"

Another program is already using the port. Start EtherPK on a different port, and use that port from then on.

No Open folder (Local Graph) button

Your browser cannot open a folder. Go back to the folder access check.