Skip to content

Installing Dive

DuckTapeKiller edited this page Sep 13, 2026 · 1 revision

This page covers downloading Dive, opening it for the first time, what happens behind the scenes when it starts, and running it from source.

Download

Every release on the Releases page has builds for three systems. For 5.0.8:

System File
macOS on Apple silicon Dive-5.0.8-arm64.dmg
macOS on Intel Dive-5.0.8-x64.dmg
Windows, installer Dive-Setup-5.0.8-x64.exe
Windows, no installation Dive-Portable-5.0.8-x64.exe
Linux Dive-5.0.8-x86_64.AppImage or Dive-5.0.8-amd64.deb

The desktop app doesn't need Node.js installed. Each mode needs its own backend, though: a local model server, the pi agent or a cloud API key. Choosing a mode lists what each one needs.

First launch on macOS

The macOS app isn't signed with an Apple developer certificate, so the first time you open it macOS may say that Dive is damaged or can't be opened. Clear the quarantine flag once in Terminal, using the path where you put the app:

xattr -dr com.apple.quarantine /Applications/Dive.app

Then open Dive normally.

What happens when Dive starts

This matters when something doesn't start, and when you want to know which copy of the code is running. The steps are in electron/main.js:

  1. Pick the port. Dive reads serverPort from ~/dive/pi-settings.json. Without one, or with a value outside 1024 to 65535, it uses 8080.
  2. Copy the server. syncRuntimeFiles() copies the server code from the app into a runtime folder inside the app's user data folder, overwriting the previous copy. On macOS that is ~/Library/Application Support/dive-desktop/runtime.
  3. Start the server.
    • On macOS, Dive writes a LaunchAgent at ~/Library/LaunchAgents/com.dive.server.plist and starts it with launchctl. The agent runs runtime/server.js with the node it finds on your PATH, and keeps it running, so the server stays up after you close the window. Its output goes to launchagent.out.log and launchagent.err.log in ~/Library/Application Support/dive-desktop.
    • On Windows and Linux, Dive runs runtime/server.js as a child process with its own executable, and stops it when you close the window.
  4. Wait for it. Dive asks the server for /api/models until it answers: up to 6 seconds on macOS and 15 seconds elsewhere. If it gets no answer, Dive loads the server inside its own process instead. This is also what happens on a Mac without Node.js, where no LaunchAgent can be installed: start-up takes a few seconds longer, and the server stops when you quit.
  5. Open the window at http://127.0.0.1:<port>.

Opening Dive a second time brings the existing window to the front instead of starting another copy.

Because the server is an ordinary local web server, you can also use Dive in a web browser at http://127.0.0.1:8080 (or your port) while the server is running.

Where your data lives

Everything Dive keeps is in one folder: ~/dive, the dive folder in your home folder, on every system. That includes conversations, settings, notes, skills, external tools and the library index. Copy that folder and you have a full backup. Data folder and settings lists every file.

To use a different folder, for a test profile say, set DIVE_DATA_DIR before starting Dive or the server:

DIVE_DATA_DIR=~/dive-test npm run dev:web

The runtime folder is only a copy of the app's code. It is rebuilt on every launch, so there is nothing in it to back up.

Optional extras

  • PDF uploads. Dive reads PDFs with pdftotext, which comes with Poppler. On macOS: brew install poppler.
  • Node.js on macOS. Having node on your PATH lets Dive run its server as a LaunchAgent, so it keeps running in the background.

Uploads accept .txt, .md, .js, .ts, .py, .html, .css, .json, .pdf, .jpg, .jpeg, .png, .gif and .webp files.

Changing the port

Switch to Pi mode, open Settings, and find SERVER PORT under PI EXECUTION on the MAIN tab. The field sits with the Pi settings, but the port is used by the whole app: Dive saves it as serverPort in ~/dive/pi-settings.json, and reads it on the next launch. Relaunch Dive for the change to apply.

Updating

Install the new release over the old one. On the next launch Dive copies the new server code into runtime and, on macOS, rewrites and restarts its LaunchAgent. Your ~/dive folder stays where it is.

Uninstalling on macOS

Stop and remove the background server first:

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.dive.server.plist
rm ~/Library/LaunchAgents/com.dive.server.plist

Then delete Dive.app. You can also delete ~/Library/Application Support/dive-desktop. Delete ~/dive only if you no longer want your conversations, settings and library.

Running from source

You need Node.js 20 or later and git.

git clone https://github.com/DuckTapeKiller/dive.git
cd dive
npm install
npm run dev:web

npm run dev:web runs node server.js. Open http://127.0.0.1:8080 in your browser. The other useful scripts:

Command What it does
npm run dev:app Runs the desktop window with electron .
./run.sh macOS: checks Node.js, installs dependencies if they're missing, warns if Ollama isn't running, starts the server and opens your browser
npm run build:dmg Builds the macOS disk image
npm run build:win Builds the Windows installer and portable app
npm run build:linux Builds the AppImage and .deb
npm test Runs the test suite

Use DIVE_DATA_DIR while developing so your experiments stay out of your real ~/dive.

If it doesn't start

  • listen EADDRINUSE 127.0.0.1:8080 means something else already uses the port. Usually that is another Dive server: the app's LaunchAgent, or the com.user.dive LaunchAgent that the repository's install-launchagent.sh installs for source checkouts. Stop the other one or change the port.
  • A blank window means the server didn't answer. On macOS, check launchagent.err.log in ~/Library/Application Support/dive-desktop.

More in Troubleshooting.

Clone this wiki locally