Install and remove

Choose a package for your Mac, Windows or Linux computer, open it past the first-time warning, set Nocturne up and take it off again, or run it as a server in a container.

What your computer needs

Nocturne works on:

  • a Mac with an Apple chip (M1 or later), running macOS 26 or later. Older Intel Macs are not supported;
  • a Windows 10 or 11 computer, 64-bit;
  • a Linux desktop, on a 64-bit computer with an Intel, AMD or Arm chip.

The first time it runs, it checks the memory and free space and offers the largest setup the computer can carry comfortably. A smaller setup means slower answers and a slower overnight tidy; everything still works.

Setup Memory it needs Free space it needs One-off download
Large 60 GB or more about 28 GB about 26 GB
Standard 28 GB or more about 11 GB about 8.5 GB
Small 14 GB or more about 7 GB about 5 GB
Tiny 6 GB or more about 5.2 GB about 3.2 GB

The free space figure includes 2 GB of room to spare. You can always choose a smaller setup than the one offered: it uses less memory, space and battery. Tiny is made for 8 GB computers, which report a little under 8 GB, and it runs on anything that reports 6 GB or more; everything works, but its answers are simpler and it may miss details. If the computer has less memory than the Tiny setup needs, Nocturne says so plainly and downloads nothing.

Choose a package

Download the one file for your computer from the latest release. Each has a fixed name, so these links always give the newest version:

Computer File Choose it when
Mac Nocturne-macos-arm64.dmg You have a Mac with an Apple chip
Windows Nocturne-windows-x64-setup.exe You use Windows at home. This is the usual choice
Windows Nocturne-windows-x64.msi Your computer is managed by an organisation that installs .msi files
Linux Nocturne-linux-x86_64.AppImage You want to try Nocturne without installing it, or your desktop is not Fedora or Debian based
Linux Nocturne-linux-x86_64.rpm Your computer runs Fedora, Red Hat, openSUSE or something similar
Linux Nocturne-linux-amd64.deb Your computer runs Debian, Ubuntu, Linux Mint or something similar
Linux on Arm Nocturne-linux-aarch64.AppImage As the AppImage above, on a computer with an Arm chip
Linux on Arm Nocturne-linux-aarch64.rpm As the rpm above, on a computer with an Arm chip
Linux on Arm Nocturne-linux-arm64.deb As the deb above, on a computer with an Arm chip
Linux Flatpak You want your software centre to keep Nocturne up to date, on any Linux desktop, Arm included

Most Linux computers have an Intel or AMD chip and take the plain Linux files. If yours has an Arm chip, take the Linux on Arm files instead. To check, run uname -m in a terminal: x86_64 means the plain files, aarch64 means the Arm ones. The Flatpak picks the right one by itself.

The release also has a list of fingerprints to check the files against (SHA256SUMS). The release page names each file with its version number as well; those are the same files.

Nocturne is not signed by Apple or Microsoft, because each charges a yearly fee. Your Mac or Windows computer therefore warns you the first time, and the next section shows what to click. The Linux Flatpak is signed with Nocturne's own key. To be sure a download is the one we published, check it against SHA256SUMS before you open it. Put the file and SHA256SUMS in the same folder and run:

sha256sum --check --ignore-missing SHA256SUMS

On a Mac, run shasum -a 256 --check --ignore-missing SHA256SUMS instead. On Windows, run Get-FileHash <file> in PowerShell and compare the result with the line for that file in SHA256SUMS. The list covers every file, so --ignore-missing skips the ones you did not download. Each file it checks should say OK. If one does not, do not open it.

The first time you open it

On a Mac

  1. Open the downloaded .dmg file, then drag Nocturne into Applications.
  2. Open Nocturne from Applications. Your Mac says "Nocturne" Not Opened, because it could not check the app. Click Done.
  3. Open System Settings, then Privacy & Security. Scroll down to the line saying Nocturne was blocked and click Open Anyway.
  4. Enter your password, then click Open Anyway again.

You only do this once. After that, Nocturne opens like any other app. On macOS before Sequoia (version 15), Control-click Nocturne in Applications and choose Open instead.

On Windows

  1. Your browser may warn that the download is not commonly downloaded. In Edge, open the ... menu beside the file, choose Keep, then Show more, then Keep anyway.
  2. Open the installer. Windows shows "Windows protected your PC". Click More info, then Run anyway.

You only do this once per download. If you see no warning, there is nothing to click.

On Linux

There is no warning. See the notes for your package below.

Linux packages

AppImage

Make the file runnable, then open it:

chmod +x Nocturne-linux-x86_64.AppImage
./Nocturne-linux-x86_64.AppImage

On a computer with an Arm chip, the file is Nocturne-linux-aarch64.AppImage; use that name in these commands. Keep the file where you will find it again. It carries everything it needs, including its own copy of the parts that run Nocturne's private reading engine.

An AppImage opens by mounting itself, which needs FUSE on your computer (most desktops have it). If it will not open for that reason, run it this way instead, which unpacks it for the run:

./Nocturne-linux-x86_64.AppImage --appimage-extract-and-run

If you move the AppImage to another folder, turn "Start with this computer" off and on again in Settings, and copy the shortcut command shown there again, so both point at the new place.

rpm

sudo dnf install ./Nocturne-linux-x86_64.rpm

On a computer with an Arm chip, install Nocturne-linux-aarch64.rpm the same way.

Your software centre can open the file too. Nocturne then appears in your applications list.

deb

sudo apt install ./Nocturne-linux-amd64.deb

On a computer with an Arm chip, install Nocturne-linux-arm64.deb the same way.

Flatpak

Add Nocturne's repository from flatpak.nocturne.is, then install the app. The page has a button that does both, or run:

flatpak remote-add --user --if-not-exists nocturne https://flatpak.nocturne.is/nocturne.flatpakrepo
flatpak install --user nocturne is.nocturne.Nocturne

Your software centre then shows Nocturne and its updates. The Flatpak keeps everything it holds in its own folder and sees only the files you choose or drop on it. Starting with your computer is not available in the Flatpak yet.

Run it as a server

This part is for technical people, and the server is experimental. Instead of a desktop app, Nocturne runs in a container on a machine that is always on, and you use it from a browser. It is the same app with the same private engine, and it keeps everything in one volume. What needs a desktop (the tray, starting with the computer, notifications, printing, choosing folders, Away from home) is not there. Decision 0012 has the details.

Releases publish the image as ghcr.io/agync/nocturne. Until one has, build it yourself with make server/image (building) and use localhost/nocturne:dev in place of the name below.

podman run -d --name nocturne \
  -p 127.0.0.1:55066:55066 \
  -v nocturne-data:/data \
  ghcr.io/agync/nocturne:latest
podman exec nocturne nocturne-server token     # the sign-in link

Docker takes the same flags (docker run ..., docker exec ...). Open the link it prints, http://127.0.0.1:55066/#token=..., in a new tab, once in each browser you use; the browser keeps you signed in. The link is never written to the container's log. To publish another port on this machine, say so with -e NOCTURNE_PUBLIC_ORIGIN=http://127.0.0.1:<port>.

Command What it does
podman exec nocturne nocturne-server token Prints the sign-in link
podman exec nocturne nocturne-server token --rotate Makes a new link; the old one stops working at once
podman exec nocturne nocturne-server health Exits 0 while the server is up; the image's health check runs it

The link is the only key, so keep it like a password. If you think it leaked, rotate it: within a few seconds the old link stops working in every browser that used it.

Reach it from other devices

The port is published on this machine's loopback only, and the server accepts plain HTTP only from this machine. To use it from a phone or another computer, put a TLS proxy in front and tell the server its address with NOCTURNE_PUBLIC_ORIGIN. It must be https://, with no path. The server does not start with a plain http:// address other than this machine's.

With Caddy, which gets a certificate for the name by itself:

nocturne.example.com {
    reverse_proxy 127.0.0.1:55066
}

With Tailscale, inside your own tailnet:

tailscale serve --bg --https=443 http://127.0.0.1:55066

Then start the container with the address the proxy serves, for example -e NOCTURNE_PUBLIC_ORIGIN=https://nocturne.example.com or -e NOCTURNE_PUBLIC_ORIGIN=https://<machine>.<tailnet>.ts.net, and print the link again: it now starts with that address. If the proxy already serves something else on that name and port, give Nocturne a port of its own (--https=8443) and include the port in the address.

Compose

services:
  nocturne:
    image: ghcr.io/agync/nocturne:latest
    ports:
      - "127.0.0.1:55066:55066"
    volumes:
      - nocturne-data:/data
    environment:
      NOCTURNE_PUBLIC_ORIGIN: https://nocturne.example.com
    restart: unless-stopped
volumes:
  nocturne-data: {}

podman compose up -d or docker compose up -d starts it.

Your data, updates and removal

Everything lives in the nocturne-data volume: what you kept, the memory, the downloaded setup, the logs (logs/) and the sign-in token. The first visit offers the usual setup, which downloads once, with your consent, into the volume. To keep a folder of your own instead of a named volume, make it owned by the container's user first (podman unshare chown 10001:10001 <folder> with rootless podman) and mount it with -v <folder>:/data:Z.

To update, pull the new image and start a new container on the same volume:

podman pull ghcr.io/agync/nocturne:latest
podman rm -f nocturne
podman run -d --name nocturne -p 127.0.0.1:55066:55066 -v nocturne-data:/data ghcr.io/agync/nocturne:latest

To take it off, remove the container. The volume stays until you remove it yourself with podman volume rm nocturne-data, which deletes everything you kept.

Graphics cards

On a computer you use directly, Nocturne uses the graphics in it when the private engine finds some that work: AMD, Intel or NVIDIA. Without any, it runs on the processor, which is slower but does everything.

In a container the image runs on the processor and needs nothing more. A graphics card is optional, and the published image does not carry the drivers for one. Do not pass a graphics device to it.

For an AMD Radeon that Nocturne uses through Vulkan (the usual case for one built into the processor), build the image with the Vulkan drivers and pass the device in:

podman build --format docker --build-arg EXTRA_PACKAGES=mesa-vulkan-drivers \
  -f Containerfile -t localhost/nocturne:vulkan .
podman run -d --name nocturne --device /dev/dri \
  -p 127.0.0.1:55066:55066 -v nocturne-data:/data localhost/nocturne:vulkan

With rootless podman, your own user must be able to open /dev/dri/renderD128; if it can only through the render group, add --group-add keep-groups. This was tried with rootless podman on a Radeon 890M, where the model servers opened the card. A discrete AMD card would use ROCm, which needs --device /dev/kfd --device /dev/dri. Intel graphics take the same Vulkan build and device. An NVIDIA card needs NVIDIA's own driver and container tooling.

The first run

Nocturne opens a short setup:

  1. It looks at your computer and tells you which setup it will use.
  2. It downloads that setup once. It asks before it downloads. This is the only time Nocturne uses the internet. You can keep things straight away while it downloads, and the download carries on by itself if the connection drops.
  3. It tells you when it is ready. Your first page arrives the next morning.

After setup, Nocturne works with no internet at all.

Take Nocturne off

Removing the app does not remove what you kept. Your things stay in your data folder until you delete them yourself (see Your data).

  • Mac: drag Nocturne from Applications to the Bin.
  • Windows: open Settings, Apps, find Nocturne and choose Uninstall.
  • AppImage: delete the file.
  • rpm: sudo dnf remove nocturne
  • deb: sudo apt remove nocturne
  • Flatpak: flatpak uninstall --user is.nocturne.Nocturne. Your things stay in ~/.var/app/is.nocturne.Nocturne/ until you delete that folder.

If you turned on "Start with this computer", turn it off in Settings first. Otherwise your desktop keeps a start-up entry for a program that is no longer there.

Connections

Local graph

Linked from