Repository navigation
Installing Dive
This page covers downloading Dive, opening it for the first time, what happens behind the scenes when it starts, and running it from source.
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.
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.appThen open Dive normally.
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:
-
Pick the port. Dive reads
serverPortfrom~/dive/pi-settings.json. Without one, or with a value outside 1024 to 65535, it uses 8080. -
Copy the server.
syncRuntimeFiles()copies the server code from the app into aruntimefolder inside the app's user data folder, overwriting the previous copy. On macOS that is~/Library/Application Support/dive-desktop/runtime. -
Start the server.
- On macOS, Dive writes a LaunchAgent at
~/Library/LaunchAgents/com.dive.server.plistand starts it withlaunchctl. The agent runsruntime/server.jswith thenodeit finds on your PATH, and keeps it running, so the server stays up after you close the window. Its output goes tolaunchagent.out.logandlaunchagent.err.login~/Library/Application Support/dive-desktop. - On Windows and Linux, Dive runs
runtime/server.jsas a child process with its own executable, and stops it when you close the window.
- On macOS, Dive writes a LaunchAgent at
-
Wait for it. Dive asks the server for
/api/modelsuntil 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. -
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.
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:webThe 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.
-
PDF uploads. Dive reads PDFs with
pdftotext, which comes with Poppler. On macOS:brew install poppler. -
Node.js on macOS. Having
nodeon 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.
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.
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.
Stop and remove the background server first:
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.dive.server.plist
rm ~/Library/LaunchAgents/com.dive.server.plistThen 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.
You need Node.js 20 or later and git.
git clone https://github.com/DuckTapeKiller/dive.git
cd dive
npm install
npm run dev:webnpm 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.
-
listen EADDRINUSE 127.0.0.1:8080means something else already uses the port. Usually that is another Dive server: the app's LaunchAgent, or thecom.user.diveLaunchAgent that the repository'sinstall-launchagent.shinstalls 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.login~/Library/Application Support/dive-desktop.
More in Troubleshooting.
These pages describe Dive 5.0.8. Source code: DuckTapeKiller/dive. Spotted a mistake? Open an issue.
Get started
Tools and skills
Build your own
Share and stay safe
How Dive works
Help