Installation

• Linux · macOS · Windows
• One binary
• Port 8091
• Updated for v0.27.1

Install on Linux or macOS

The same command works on both. It detects your OS, CPU (x64 or arm64) and, on Linux, glibc or musl, then installs the matching binary:

$curl -fsSL https://get.vaultbase.dev | sudo sh

Copy

Quick start → Releases

The script downloads the binary from the latest GitHub release and checks its SHA-256. On Linux it then sets up the service:

Binary

/usr/local/bin/vaultbase

Data

/var/lib/vaultbase, owned by a vaultbase system user

Config

/etc/vaultbase/vaultbase.env, with a generated JWT secret and setup key

Service

Hardened systemd unit, enabled and started on :8091

Re-run it any time to upgrade: the binary is replaced and the service restarted. Data, config, the JWT secret, the setup key and admin accounts are kept. Flags go after sh -s --:

Terminal

curl -fsSL https://get.vaultbase.dev | sudo sh -s -- --verify-sig --port 9000

--verify-sig

Check the binary's cosign signature first. Needs cosign on your PATH

--version

Pin a release, e.g. v0.27.1

--port

Listen on another port

--no-start

Install, but start it later (configure your proxy first)

--no-systemd

Skip the systemd unit (containers, runit)

--install-dir

Put the binary somewhere other than /usr/local/bin

On macOS the script only installs the binary to /usr/local/bin; there is no service. Start it with vaultbase, and data goes in ./vaultbase_data unless VAULTBASE_DATA_DIR is set. --port, --no-start and --no-systemd have no effect there. If you can write to the folder you don’t need sudo:

Terminal

curl -fsSL https://get.vaultbase.dev | sh -s -- --install-dir ~/.local/bin

Install on Windows

In PowerShell (no admin rights needed):

$irm https://get.vaultbase.dev/install.ps1 | iex

Copy

Quick start → Releases

It downloads vaultbase-windows-x64.exe, checks it against the release’s SHA256SUMS, installs it to %LOCALAPPDATA%\Programs\Vaultbase\vaultbase.exe and adds that folder to your user PATH. Open a new terminal and run vaultbase. On Windows on ARM the x64 binary runs under emulation.

To pass options, run the script as a script block:

PowerShell

& ([scriptblock]::Create((irm https://get.vaultbase.dev/install.ps1))) -Version v0.27.1 -VerifySig

-Version

Pin a release

-InstallDir

Install somewhere else

-VerifySig

Check the cosign signature first. Needs cosign on your PATH

-NoPath

Don't touch your PATH

Re-run it to upgrade. Stop any running vaultbase.exe first.

Download a binary

To install by hand, every release attaches a binary per target, each with a cosign signature and a CycloneDX SBOM, plus a combined SHA256SUMS file:

macOS · Apple silicon

vaultbase-macos-arm64

macOS · Intel

vaultbase-macos-x64

Windows · x64

vaultbase-windows-x64.exe

Linux

vaultbase-linux-x64, -linux-arm64, -linux-x64-musl (also as .xz)

Check the download against the combined checksum file, then run it:

Terminal

shasum -a 256 -c SHA256SUMS --ignore-missing
chmod +x vaultbase-macos-arm64
./vaultbase-macos-arm64

Build from source

You need Bun ≥ 1.4.2. No C compiler: Bun ships its own SQLite through bun:sqlite.

Terminal

git clone https://github.com/vaultbase-sh/vaultbase
cd vaultbase
bun install
(cd admin && bun install)   # the admin UI has its own dependencies
bun run build   # admin UI + binary → ./vaultbase (vaultbase.exe on Windows)
./vaultbase

To work on the admin UI, run the server and the admin dev server side by side:

Terminal

bun run dev         # server on :8091
bun run dev:admin   # admin on :5173, proxies /api to localhost:8091

The build compiles the React admin and embeds it in the binary through a Bun macro that gzips every static asset at compile time. The result is one file of about 90 MB.

Bun cross-compiles from any host, so a Mac can build the Linux binaries:

Linux

bun run build:linux-x64        # → releases/vaultbase-linux-x64
bun run build:linux-arm64      # → releases/vaultbase-linux-arm64
bun run build:linux-x64-musl   # → releases/vaultbase-linux-x64-musl

macOS

bun run build:macos-arm64      # → releases/vaultbase-macos-arm64
bun run build:macos-x64        # → releases/vaultbase-macos-x64

Windows

bun run build:windows-x64      # → releases/vaultbase-windows-x64.exe

All six

bun run build:all

Don’t pack it with UPX

UPX corrupts the code Bun embeds in the binary: the packed file still prints --version, then fails to start. For a smaller download, the Linux releases ship as .xz (about a third of the size); xz -d restores the original.

Choose your database

Pick one before the first admin is created; the server uses exactly one, and nothing is copied between them.

SQLite (default)

Nothing to do. The database is data.db in the data directory, backups are a copy of it, and one server uses every core. Right for a single box, which is most installs.

Postgres (beta)

Point VAULTBASE_DATABASE_URL at an empty Postgres 16+ database before the first start; the server creates the schema. Use it for several servers in front of one database, or a managed database your provider runs.

With the Linux installer, install without starting, add the URL to the config, then start:

Terminal

curl -fsSL https://get.vaultbase.dev | sudo sh -s -- --no-start
echo 'VAULTBASE_DATABASE_URL=postgres://vaultbase:<password>@db.internal:5432/vaultbase' | sudo tee -a /etc/vaultbase/vaultbase.env
sudo systemctl start vaultbase

Anywhere else, set the variable when you start it:

Terminal

VAULTBASE_DATABASE_URL=postgres://… ./vaultbase

What differs, what isn’t on Postgres yet, and what several servers need: Databases.

The setup wizard’s first step shows which database the server is on. To switch before creating the admin, stop the server, set or remove VAULTBASE_DATABASE_URL, and start it again.

Run it

Terminal

./vaultbase                              # listens on :8091
VAULTBASE_PORT=3000 ./vaultbase          # another port
VAULTBASE_DATA_DIR=/srv/vb ./vaultbase   # data, uploads and secrets here

On first launch Vaultbase creates the data directory:

Database

data.db, on SQLite

Uploads

uploads/, with a .thumbs/ cache

Logs

logs/, append-only, one JSONL file per day, deleted after 30 days by default

JWT secret

.secret, generated if VAULTBASE_JWT_SECRET isn't set

Encryption key

.encryption-key, generated if VAULTBASE_ENCRYPTION_KEY isn't set. Back it up with the database: encrypted values can't be read without it

Open the /_/setup#key=… link the server prints at startup to run the setup wizard. The setup key in it is required to create the first admin; it is also printed on its own line, and stored in <dataDir>/.setup-key until an admin exists. On a headless server, create the first admin from the CLI instead (it reads /etc/vaultbase/vaultbase.env when present):

Terminal

sudo vaultbase setup-admin --email you@example.com --password '<password>'

Run in Docker

The single binary makes the image a COPY and a CMD:

Dockerfile

FROM debian:bookworm-slim
COPY releases/vaultbase-linux-x64 /usr/local/bin/vaultbase
EXPOSE 8091
ENV VAULTBASE_DATA_DIR=/data
VOLUME ["/data"]
CMD ["vaultbase"]

Terminal

docker build -t vaultbase .
docker run -p 8091:8091 -v vaultbase-data:/data vaultbase

Point load balancer and orchestrator readiness checks at /_/ready, and liveness checks at /_/health. See Health and readiness.

Configure

Environment variables cover what the process needs before it boots:

VAULTBASE_PORT

Listen port. Default 8091

VAULTBASE_HOST

Bind host. Default: every interface, IPv4 and IPv6; use 127.0.0.1 behind a local reverse proxy

VAULTBASE_SETUP_KEY

Key for first-admin setup. Default: generated at first boot and printed

VAULTBASE_DATA_DIR

Database, uploads, logs and secrets. Default ./vaultbase_data

VAULTBASE_DATABASE_URL

A Postgres URL (postgres://…) to use instead of the SQLite file; see [Databases](/concepts/databases/). Beta

VAULTBASE_JWT_SECRET

Signing secret. Default: generated into <dataDir>/.secret

VAULTBASE_ENCRYPTION_KEY

At-rest key for secret settings and encrypted fields. 32 bytes as base64, hex or a 32-char string. Default: generated into <dataDir>/.encryption-key

VAULTBASE_TRUSTED_PROXIES

Comma-separated peer IPs trusted for X-Forwarded-For

VAULTBASE_READ_WORKERS

Read worker threads for record list and get-one requests. Default: CPU cores minus two (at least 1 on two cores or more), at most 8; 0 keeps one thread

VAULTBASE_WORKER_LISTENERS

Whether read workers also accept connections on the server's port (since v0.27.0). Default: on for Linux, off on macOS and Windows; 0 off, 1 on

VAULTBASE_WORKERS

Worker count for vaultbase cluster (deprecated). Default: CPU cores

VAULTBASE_GROUP_COMMIT

0 commits every record write on its own instead of sharing commits. Default: shared (off under vaultbase cluster)

Everything else (rate limits, SMTP, OAuth credentials, email templates, auth options) lives in the vaultbase_settings table and is edited from the admin Settings page.

What’s next

Getting started Quick start Your first collection and record Guides Deployment Reverse proxy, TLS and cluster mode Guides Backups & migrations Snapshots and restores Reference Settings keys Everything in the Settings page