Pre-1.0 hoardDB is pre-1.0. Expect breaking changes.

Installation

Three ways to get hoardDB running: build it from source, run it in Docker, or run a three-node cluster with docker compose. Each ends at the same place — a server answering on port 7433 and a CLI that can log in to it — and Getting started takes it from there.

hoardDB is two programs:

In the Docker image the same programs are installed as hoarddb-server and hoarddb.

Supported platforms

Windows is supported through WSL2, using the Linux binaries. The platform build (scripts/build-matrix.sh, below) compiles with cgo off, so its binaries have no C library dependency and a Linux binary runs on any distribution of the matching architecture.

Release binaries

Release downloads are not published yet. Until they are, build the same binaries yourself; the next section shows how, and scripts/build-matrix.sh builds all eight at once (below).

A release carries one server and one CLI per platform, named hoarddb-server-<os>-<arch> and hoarddb-cli-<os>-<arch>, plus a checksums.txt of their SHA-256 sums. After downloading, check them before you run anything:

sha256sum -c checksums.txt          # Linux
shasum -a 256 -c checksums.txt      # macOS

Each line should end in OK. The checksum file lists every platform’s files, so sha256sum reports the ones you did not download as missing; add --ignore-missing to skip them.

Build from source

You need Go 1.26.8 or newer (the go line in go.mod). If your Go is older but recent enough to manage toolchains (Go 1.21 or later), the go command downloads the right one the first time you build; it needs network access once to do so.

In the directory that holds go.mod:

make build

That writes hoardDB-server and hoardDB-cli into that directory, with the version and commit stamped in. Without make:

go build -o hoardDB-server ./cmd/server
go build -o hoardDB-cli    ./cmd/cli

Check what you built:

./hoardDB-server -v
./hoardDB-cli -v

hoardDB-server version=8f479df commit=8f479df build_date=2026-10-03T11:47:07Z protocol=1
hoardDB version=8f479df commit=8f479df build_date=2026-10-03T11:47:07Z protocol=1

A plain go build reports version=devel. That is honest, not an error: an untagged build is not a release.

Put them on your PATH if you like:

sudo mv hoardDB-server hoardDB-cli /usr/local/bin/

Build every platform

To produce all four platforms’ binaries and their checksums, run this from the root of the checkout:

scripts/build-matrix.sh

It cross-builds the server and the CLI for linux/amd64, linux/arm64, darwin/arm64 and darwin/amd64, checks with file that each file is the architecture its name says, and writes everything to dist/, ending with dist/checksums.txt. It needs go and file.

Start it

./hoardDB-server

With no configuration it creates ./data in the working directory, generates a self-signed certificate and a root credential (printed once, and saved to ./data/root.password at mode 0600), and listens on 127.0.0.1:7433 for clients and 127.0.0.1:4434 for other nodes. That is this machine only: nothing on the network can reach it. To accept clients from other machines set HOARDDB_TCP_LISTEN=0.0.0.0:7433; to run a cluster across machines set HOARDDB_LISTEN to each node’s own address (Security). In another terminal:

./hoardDB-cli -insecure

-insecure skips certificate verification and is for a server you started yourself on the same machine. Security shows the other way.

Docker

The Dockerfile at the root of the checkout builds a small image with both programs, running as an unprivileged user (uid 1000) with /data as the data directory.

docker build -t hoarddb:local .

If you mount a YAML config file into the container, note that the image sets HOARDDB_DATA_DIR, HOARDDB_LISTEN, HOARDDB_TCP_LISTEN and HOARDDB_METRICS_LISTEN, and environment variables win over the file. storage.data_dir, server.listen, tcp.listen and metrics.listen in a mounted file are silently ignored; set the value you want with -e instead (for example -e HOARDDB_TCP_LISTEN=0.0.0.0:7433), or -e NAME= to hand the setting back to the file.

Run one node. The volume keeps your data when the container is replaced, and choosing the root password yourself means you do not have to fish it out of the logs:

docker run -d --name hoarddb \
  -p 7433:7433 \
  -v hoarddb-data:/data \
  -e HOARDDB_ROOT_PASSWORD='choose-a-long-password' \
  hoarddb:local

Port 7433 is the only one a single node needs published. Without -v, the data lives and dies with the container.

Connect from the host with the CLI you built above:

HOARDDB_ROOT_PASSWORD='choose-a-long-password' ./hoardDB-cli -insecure

or use the CLI inside the container. It needs no password in either case: when you set HOARDDB_ROOT_PASSWORD on docker run, as above, the CLI inherits it from the container’s environment; when you did not, the server saved a generated password to /data/root.password and the CLI reads that:

docker exec -it hoarddb hoarddb -insecure

If you did not set HOARDDB_ROOT_PASSWORD, the server generated one and printed it once, in the container’s logs:

docker logs hoarddb 2>&1 | grep -A3 "ROOT CREDENTIALS"

Stop and remove the container, and keep or delete the data:

docker rm -f hoarddb
docker volume rm hoarddb-data      # only if you want the data gone

A three-node cluster with docker compose

docker-compose.yml at the root of the checkout starts three nodes with a replication factor of 3:

docker compose up -d --build

The first run builds the image, then a one-shot service generates a certificate for each node, the list of fingerprints the nodes use to recognise one another, and a shared cluster token. All three nodes then start and join.

The image listens on every interface inside the container (the binary itself defaults to loopback; the image sets HOARDDB_LISTEN, HOARDDB_TCP_LISTEN and HOARDDB_METRICS_LISTEN to 0.0.0.0, and each compose node sets HOARDDB_LISTEN to its own name). The root user is admin and the default password is test123, and the ports above are published on every interface of the host. That is fine on a laptop and not on a server; choose your own password when you start it, and firewall the ports from anything that should not reach them:

HOARDDB_ROOT_PASSWORD='choose-a-long-password' docker compose up -d --build

The compose file is for one host. To spread a cluster over several Docker hosts, set HOARDDB_LISTEN on each node to that host’s reachable address (for example HOARDDB_LISTEN=10.0.0.1:4433, and the same address in HOARDDB_SEED_NODES), or give each node a HOARDDB_NODE_ID and list the seeds as id@address. The image’s default of HOARDDB_LISTEN=0.0.0.0:4433 otherwise makes the node advertise 127.0.0.1 to its peers.

Connect to any node. Write through one and read through another to see the replication:

./hoardDB-cli -address localhost:7433 -insecure -user admin -password test123
./hoardDB-cli -address localhost:7434 -insecure -user admin -password test123

A read served by a replica that has not yet received a write you just made can miss it; use consistent get when you need to read your own write. See Replication.

An optional load balancer in front of the three client ports:

docker compose --profile proxy up -d
./hoardDB-cli -address localhost:8443 -insecure -user admin -password test123

Take it all down, keeping the data volumes, or deleting them too:

docker compose down
docker compose down -v

Upgrading

Read Compatibility and versions before you upgrade a node that holds data you care about. In short: back up the whole data directory first, upgrade every node of a cluster together, and do not expect to roll back by starting the old build on the new data.

If it does not start

• bind: address already in use — something else holds 7433 (or 4434). Stop it, or set HOARDDB_TCP_LISTEN to another address.
• A client on another machine gets “connection refused” — the server listens on 127.0.0.1 unless told otherwise. Set HOARDDB_TCP_LISTEN=0.0.0.0:7433 (or one interface’s address) and restart. The start-up log says which addresses the node is listening on.
• The server refuses to start and names HOARDDB_LISTEN — it has seeds on other machines but is still listening on loopback, so its peers could not reach it. Set HOARDDB_LISTEN to this node’s own address, for example 10.0.0.1:4433.
• The CLI says the server is not trusted — it has never seen this server’s certificate and refuses to trust it without asking. Pass -insecure for a local server, or see Security.
• The CLI says no credentials — it could not find the saved root password (it looks for ./data/root.password). Pass -user and -password, or set HOARDDB_ROOT_USER and HOARDDB_ROOT_PASSWORD.
• A container exits straight away — read docker logs hoarddb; the server logs the reason in its last lines.

Source: docs/user/installation.md in the repository.