Hivekeep Configure
Install

Install Hivekeep.

One recommended way for everyone, plus options if you want a domain, a custom port, or Docker. Whichever you pick, once it's up Queenie sets up the rest by chatting with you. No config files to edit.

Recommended for everyone

The one-line install.

Paste this into a terminal on your Linux or macOS machine. It does everything for you, then opens in your browser.

curl -fsSL https://raw.githubusercontent.com/MarlBurroW/hivekeep/main/install.sh | bash
What it does to your machine
  • Installs Bun if it is missing
  • Clones Hivekeep into its own folder and builds it
  • Auto-generates and saves an encryption key at $DATA_DIR/.encryption-key so your secrets survive restarts
  • Sets it up as an optional background service and starts it
If something goes wrong
  • "port already allocated" / address in use: something else uses port 3000. Use the configurator below to pick another port, e.g. 3001.
  • Windows? The native installer is Linux and macOS only. Use WSL2 and run it inside your Linux shell, or use Docker Desktop.
  • Stuck downloading? Make sure the machine can reach github.com and bun.sh over HTTPS (corporate proxies often block these).
Before you start

What the native install needs.

Most machines already have all of this. Quick checklist:

You can run sudo
The installer needs it to install missing system packages (git, curl, unzip).
About 500 MB free disk
Room to clone and build. 1 GB or more is comfortable.
A 64-bit machine
x86_64 or ARM64. 32-bit (older Raspberry Pi) is not supported.
Outbound HTTPS
It downloads from github.com and bun.sh, so those must be reachable.
openssl present
Used to generate keys. It ships with almost every Linux and macOS.

On Windows? The native installer doesn't run on Windows directly. Use WSL2 (run the one-liner inside your Linux distro) or Docker Desktop.

Compare

Which path is right for you?

All three run the exact same app. They differ in how it lives on the machine.

Recommended

Native (install.sh)

Pick this if you just want it to work. One command, on your own Linux or macOS box.

  • One command, builds locally, no image to publish or pull
  • Saves your encryption key automatically, secrets persist
  • Runs as a service (systemd / launchd), auto-update with rollback
  • Agents own the box: install tools & deps, direct hardware access
  • Modifies the host system (by design)
  • Linux & macOS only (Windows via WSL2)
Container

Docker

Pick this if you already live in Docker and want a clean, sandboxed appliance.

  • Fully isolated, zero host pollution
  • Runs anywhere Docker runs, including Windows
  • Published image is not available yet, prefer native for now
  • Agent-installed tools & binaries don't survive a restart
  • You must persist the data volume or you lose your secrets
From source

Manual

Pick this if you want to read the code, hack on it, or run it your own way.

  • Full control: clone, build, run with Bun yourself
  • Best for contributors and development
  • No service, no auto-update, you wire those up
  • You handle Bun, build, migrations and the encryption key by hand
Configure your install

Need a port, a domain, or Docker?

Answer a couple of questions and we'll generate the exact command for your setup.

1 · How will you use it?

2 · Settings

3 · Run it

Installshell
curl -fsSL https://raw.githubusercontent.com/MarlBurroW/hivekeep/main/install.sh | bash

Your encryption key is handled for you. The installer auto-generates and saves it at $DATA_DIR/.encryption-key so your secrets survive restarts. Back up that file alongside your database. (Pin a fixed ENCRYPTION_KEY with the advanced toggle above if you'd rather manage it yourself.)

If the install fails
  • port already in use / EADDRINUSE: port 3000 is taken. Change the Port field above and re-run.
  • Windows: the installer is Linux and macOS only. Run it inside WSL2, or use Docker Desktop.
  • Download or clone hangs: make sure the machine can reach github.com and bun.sh over HTTPS (a proxy may be blocking them).

Open http://localhost:3000 in your browser. Queenie walks you through the rest (admin account, your first AI provider, your first agents). No config files to edit.