Skip to content
Vaultbase

Installation

Install the prebuilt binary with one line on Linux, macOS or Windows, or build it from source.

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

Install on Linux or macOS

Section titled “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
Quick start → Releases

The script downloads the binary from the latest GitHub release and checks its SHA-256. If the checksum can’t be fetched, it stops rather than install an unchecked binary. 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

When cosign is on your PATH, the script checks the binary’s signature before installing it; without it, the script says so and relies on the release’s .sha256 alone. A download cut short runs nothing.

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 -- --version v0.40.2 --port 9000
--verify-sig
Require the cosign signature check: fail when cosign isn't on your PATH. Without this flag the check still runs whenever cosign is installed. Only a signature from the release workflow, run for that version's tag, is accepted
--no-verify-sig
Skip the signature check even when cosign is installed, for old releases that aren't signed
--version
Pin a release, e.g. v0.40.2. Must be vX.Y.Z (an optional pre-release suffix is allowed)
--skip-checksum
Install without the SHA-256 check, for old releases that publish no checksum
--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

Section titled “Install on Windows”

In PowerShell (no admin rights needed):

irm https://get.vaultbase.dev/install.ps1 | iex
Quick start → Releases

It downloads vaultbase-windows-x64.exe, checks it against the release’s SHA256SUMS (and stops if that file can’t be fetched), checks its cosign signature when cosign is on your PATH, 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.40.2 -VerifySig
-Version
Pin a release, as vX.Y.Z
-InstallDir
Install somewhere else
-VerifySig
Require the cosign signature check: fail when cosign isn't on your PATH. Without it the check still runs whenever cosign is installed. Only a signature from the release workflow, run for that version's tag, is accepted
-NoVerifySig
Skip the signature check even when cosign is installed, for old releases that aren't signed
-NoPath
Don't touch your PATH
-SkipChecksum
Install without the checksum check, for old releases that publish no SHA256SUMS

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

Download a binary

Section titled “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

Section titled “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 127 MB.

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

Terminal window
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

Choose your database

Section titled “Choose your database”

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

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.

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

Section titled “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 -u vaultbase vaultbase setup-admin --email [email protected] --password '<password>'

Run it as the service’s user (vaultbase), not as root: files it writes in the data directory must stay readable by the service. Since 0.32.3 it refuses to run as root there and prints this command.

Run in Docker

Section titled “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

Section titled “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/)
VAULTBASE_PG_READONLY_URL
Postgres only: the login read-only SQL (the SQL page, MCP run_sql) runs as, when the server can't create one itself; see [Read-only SQL on Postgres](/concepts/databases/#read-only-sql-on-postgres)
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

Section titled “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