Get the kit first. Everything below runs from its folder. Nothing is unpacked unless the checksum line answers OK:
mkdir -p ~/securevault-server && cd ~/securevault-server \
&& curl -fsSLO https://vault.littlehelpers.se/download/securevault-server-kit-1.0.0.tar.gz \
&& echo "4b4c37c675aad97595a976b6b5a4c1539efa40b2674d30f5f3e296173941265b securevault-server-kit-1.0.0.tar.gz" | sha256sum -c - \
&& tar -xzf securevault-server-kit-1.0.0.tar.gz --strip-components=1
macOS has no sha256sum: use shasum -a 256 -c - in its place.
SecureVault keeps your vault in a database that you run yourself. The whole server is one MariaDB database (secure_vault) and one database user (vault_user) that may do nothing outside it. The app creates its own tables the first time it connects. Your devices (the SecureVault app, the agent module) connect to it over your home network or over Tailscale.
This page is for a person. If an AI agent sets the server up for you, point it at agent-setup.md on the SecureVault site instead; it contains the same steps written for an agent.
What is in the database: passwords, 2FA secrets, notes, security questions, backup codes, door codes and login guides are encrypted on your devices before they are stored (AES-256-GCM, key from your master password). Account names, usernames, e-mail addresses, websites and folders are stored in plain text. So the database must stay on networks you trust: never forward its port (3306) from your router to the internet.
Which way to host
| You have | Use | Effort |
|---|---|---|
| A Raspberry Pi, a home server or an always-on PC with Debian, Ubuntu, Raspberry Pi OS, Arch Linux or Fedora | The installer (install.sh) | One command |
| A Mac, a Windows PC, a NAS or any other computer with Docker | Docker (docker-compose.yml) | Three commands |
| A Linux machine where MariaDB already serves something else | Docker (the installer stops rather than change that MariaDB) | Three commands |
| Only an Android phone | Termux (termux.sh): for advanced users, with conditions | See that section |
The server must be on whenever a device wants the vault. A laptop that sleeps is a poor server.
Everything below runs from the kit folder (the folder this file is in).
What was tested
Every claim on this page comes from a test that was run on 2026-11-20 (the phone on 2026-11-19). The tests ran in containers on one x86-64 Linux desktop, not on separate physical machines.
| Way of hosting | Tested on | MariaDB | Not tested |
|---|---|---|---|
| Installer | Debian 12 and 13, Ubuntu 22.04 and 24.04, Arch Linux, Fedora 45, each in a container with systemd: install, second run, backup, restore, nightly timer, restart of the system, firewall, uninstall. Debian 12, Arch and Fedora also without systemd (--manual-start), and a bare Arch where neither a firewall rule nor a scheduler is possible | 10.6 to 13.0 (whatever the system ships) | Real hardware and virtual machines; SELinux (see Troubleshooting); Tailscale itself (a stand-in address was used) |
| Installer on a Raspberry Pi | Debian 12 for 64-bit ARM, emulated, without systemd and without the firewall rule | 10.11 | A real Raspberry Pi and Raspberry Pi OS itself |
| Docker | Docker Engine 29 with Compose 5 on Linux, using only docker compose commands (no shell scripts on the computer), with the clients on the same computer | 11.4 (the image mariadb:11.4) | Docker Desktop on macOS and on Windows was not run, and no shell but bash. A client on another machine (the published port was never put on a real home-network address). What could differ is named in the Docker section |
| Android phone | Samsung Galaxy A54, Android 16, Termux 0.118.3 | 13.0 | Start after a reboot, Termux swiped away, an unplugged phone in deep sleep, and more: see that section |
Each server was checked from outside with the app's own database library (Dart mysql1, both the published one and the patched copy in the app's release branch), the agent module's library and settings reader (Node mysql2), and the mariadb command-line client: sign-in, the app's tables, text in several scripts and emoji, an 80 000-byte field, and that vault_user is refused everything outside its database.
The installer (Debian, Ubuntu, Raspberry Pi OS, Arch Linux, Fedora)
sudo ./install.sh
It asks one question (is this plan right?) and then:
- installs MariaDB with your system's package manager if it is missing (on Arch it also creates the data directory), and three small packages where they are missing:
iproute2(to read the machine's addresses),nftables(the firewall rule) andqrencode(the QR code). Each gets its own==> Installing ...line, - creates the database and
vault_userwith a generated 32-character password and only these rights on that one database: select, insert, update, delete, create, alter, index, references, - makes MariaDB listen on the home network, and limits both the firewall and the account to private addresses (10.x, 172.16-31.x, 192.168.x, and Tailscale's 100.64-127.x if Tailscale is running). MariaDB itself then listens on every address of the machine (
0.0.0.0), so that a changed address does not stop it; the firewall rule and the account are what keep everything else out, - prints what the app asks for, with a
securevault://connect?c=...line and a QR code, - ends with a status table and one line that starts with
RESULT:.
In the app, on Connect to your server, paste that line (or scan the QR code with a phone).
The connect line carries this machine's address. Give the machine a fixed address in your router (a DHCP reservation), or the app loses the server when the address changes.
How a run ends is the same every time, for you and for a script or an AI agent:
SecureVault server: status
database ok vault_user signs in over the network on port 3306 (MariaDB 10.11.19)
starts after restart yes systemd starts MariaDB (mariadb.service is enabled)
firewall rule yes nftables: port 3306 answers private addresses only; loaded at every start
nightly backup yes systemd timer securevault-backup.timer
RESULT: complete
| Last line | Exit code | Meaning |
|---|---|---|
RESULT: complete | 0 | All four are in place |
RESULT: set up, but without: ... | 0 | Everything you asked for is in place; the things named were switched off on purpose or not asked for (for example no --backup-timer) |
RESULT: incomplete: ... | 3 | The database is set up, but something you asked for is missing; the no rows say what and what to do |
no RESULT: line, an ERROR: line instead | 1 | It stopped there; the message says why |
It needs root because it installs a package, writes MariaDB settings and adds a firewall rule. What it writes:
| What | Where |
|---|---|
| MariaDB settings (where it listens) | /etc/mysql/mariadb.conf.d/99-securevault.cnf (Debian, Ubuntu), /etc/my.cnf.d/zz-securevault.cnf (Arch, Fedora) |
Password, server.json, the connect line | /etc/securevault/ (root only) |
| Firewall | its own nftables table inet securevault, loaded at every start by securevault-firewall.service (the system's own nftables.service is not used and may stay off); with ufw or firewalld active, rules in those instead |
| Commands | /usr/local/sbin/securevault-server (the installer itself), securevault-backup, securevault-restore |
Useful options (./install.sh --help lists all):
| Option | What it does |
|---|---|
--tailscale | Listen on this machine's Tailscale address only. Best when you use the vault away from home |
--address IP | Listen on one private address of this machine only |
--backup-timer | Also turn on the nightly backup |
--no-firewall | No firewall rule, and you accept a server without one (stays so on later runs; --firewall turns it back on) |
--manual-start | Set it up on a system without systemd (see below) |
--port N | Another port than 3306 |
--tls | Require an encrypted connection (see "TLS") |
--hide-secrets | Do not print the password or the connect line (the default when the output is not a terminal) |
--yes | Do not ask |
Later:
sudo securevault-server --show # the connection details again
sudo securevault-server --check # can vault_user sign in on every address? and the status table again
sudo securevault-server --reset-password # new password; every device must connect again
sudo securevault-server --tailscale # change where it listens (any option can be changed by running it again)
Running the installer again changes nothing that is already right: it keeps the password and does not restart MariaDB.
It stops, and changes nothing, when:
- MariaDB is already installed and holds other databases or accounts. The installer would change where that whole server listens and restart it. Use Docker instead, or, if you decide it is fine, run it with
--use-existing-mariadb. - Oracle MySQL is installed. It only sets up MariaDB. Use Docker.
- The machine has a public internet address (a rented server, for example) and you did not choose
--tailscaleor--address. - The system does not run systemd (a container, some WSL setups). Nothing there would start the database again after a restart of the machine, so it is not a suitable host as it is: use Docker, or another machine.
If you accept a database that you start by hand after every restart, run the installer with --manual-start. The status table then says starts after restart no, and after each restart you run:
sudo securevault-server --start # starts the database, loads the firewall rule, prints the status table
On such a system the nightly backup (--backup-timer) works only if cron is running; otherwise sudo securevault-backup by hand is the only backup. --manual-start is remembered on later runs.
If the firewall rule cannot be added (for example Operation not permitted in a container or on a restricted virtual server), the run ends with RESULT: incomplete: firewall rule. The database port then answers every machine that can reach this one, and only the account's limit to private addresses guards it. Remove the cause and run the installer again, or accept it with --no-firewall.
Docker (any computer: Linux, macOS, Windows)
You need Docker with Compose (Docker Desktop on macOS and Windows; Docker Engine with the compose plugin on Linux). Nothing else: the helper scripts run in containers. Open a terminal in the kit folder and keep that folder: it will hold your settings (.env) and your backups.
First find the address of this computer on your home network (for example 192.168.1.20), or its Tailscale address (100.x.y.z) if you use Tailscale:
- Linux:
ip -4 -brief addr - macOS:
ipconfig getifaddr en0(Wi-Fi is usuallyen0) - Windows (PowerShell):
ipconfigand read "IPv4 Address" - Tailscale, any system:
tailscale ip -4
Give the computer a fixed address in your router, or the vault moves when the address does.
docker compose run --rm setup --init --address 192.168.1.20 # once: writes .env with generated passwords
docker compose up -d # starts the database and the daily backup
docker compose run --rm setup # prints what the app asks for
docker compose run --rm qr # the connect line as a QR code, for a phone
On Linux, put sudo in front of docker unless your user is in the docker group. On Linux you can also run the helper directly, and it finds the address itself: ./connect-info.sh --init, then ./connect-info.sh.
What runs: securevault-db-1 (MariaDB 11.4, data in the Docker volume securevault_securevault-data) and securevault-backup-1 (one backup a day into ./backups). Both have the restart policy unless-stopped, so Docker starts them again when it starts (tested by restarting the containers, not by restarting Docker or the computer). That only helps if Docker itself starts with the computer. On Linux check systemctl is-enabled docker.service: with disabled, Docker starts only when first used and the vault stays down after a restart until then (sudo systemctl enable docker.service changes that; not tested here).
How the Docker setup differs from the installer:
- The port is published on the one address you gave, and that is the network limit to rely on. In the tests (clients on the same computer) MariaDB inside the container saw every connection as coming from Docker's own network, so the account's address limits could not tell one client from another. How a client on another machine appears was not tested. Never use
0.0.0.0on a computer with a public address: Docker's published ports go around ufw and most firewalls. - No firewall rule is added and there is no TLS option. For use away from home, give the Tailscale address to
--init --address. - Listening on both the home network and Tailscale needs two published addresses, which this file does not do. Use the Tailscale address for both (it also works at home), or the installer.
Not tested on Docker Desktop (macOS, Windows). The steps above were run on Linux only. Things that can differ there, and were not checked: whether publishing on one specific address works the same way; the firewall of Windows or macOS asking for (or silently refusing) incoming connections on the port; file sharing for the kit folder. Also keep the kit's files with Unix line endings (unpack the .tar.gz with tar -xzf; do not let an editor or Git convert them). If a step fails there, the Troubleshooting section says what to look at.
To use another port: --init --address <IP> --port 3307. To change the address later: edit BIND_ADDRESS in .env, then docker compose up -d, then docker compose run --rm setup, and connect each device again.
Android phone (Termux)
For advanced users. A feasibility test on one phone went well, but three things that decide whether you can rely on it were not tested. Read both lists before you choose this.
What it is: MariaDB running inside the Termux app, listening on the phone's Tailscale address only.
Conditions
- Tailscale on the phone and on every device that uses the vault. Android runs one VPN at a time, so a phone that needs another VPN app cannot do this.
- Termux from F-Droid or GitHub (not the Play Store), and the Termux:Boot app, opened once, for a start after a reboot. After a reboot the phone must be unlocked once before anything starts.
- Termux holds a wake lock all the time (battery). Set battery use of Termux and Tailscale to "Unrestricted" in Android's settings.
- No firewall, and no fixed MariaDB version: Termux installs whatever is current (13.0.2 on the test day).
- The vault is reachable only while the phone is on, has a network and Termux is alive. Backups must be pulled to another device: a lost phone otherwise takes the vault and its backups with it.
Set-up, in Termux, with the kit unpacked on the phone:
pkg install -y mariadb
bash termux.sh
It ends with one line saying where the connection details are: ~/securevault/server.json and ~/securevault/connect.txt (the securevault://connect?c=... line). It never prints the password. On the same phone, show the line with cat ~/securevault/connect.txt, copy it and paste it into the app.
termux.sh is, apart from its comments, the script that was run on the test phone. In that run mariadb was already installed, a different port was used, and the boot script was switched off, so three lines of it did not run there: pkg install, the default port 3306, and writing ~/.termux/boot/start-securevault.
Tested on the phone (Samsung Galaxy A54, Android 16, 2026-11-19), in two parts:
- With this script, run once: it created the data directory, started the server, made the database, the user and the two files in 13 seconds; a desktop then signed in over Tailscale with the password from its
server.json, and the connect line decoded to the same settings. - On the same phone, with the same MariaDB and the same settings, but set up by hand and kept alive by a separate small restart loop: the app's and the agent module's database libraries over Tailscale; text and emoji; back by itself 8 seconds after the server process was killed, with nothing lost; a backup (copied to a desktop and checked there) and a restore into a scratch database; two idle periods of 16 minutes with the screen off (the phone was charging). The keep-alive loop that
termux.shwrites (run.sh) does the same job but is not the one that was killed and watched.
Not tested
| What | Why it matters |
|---|---|
| Start after a reboot (Termux:Boot) | Until you have rebooted the phone and seen it come back, assume it does not |
| Termux swiped away from the recent-apps list | May stop the server |
| An unplugged phone in deep sleep, with and without the wake lock | The idle tests ran on a charger |
| Battery cost | Could not be measured |
| Switching between Wi-Fi and mobile data with a connection open | |
| Android's process killer over days | The test ran 45 minutes |
Running termux.sh a second time, the stop.sh and backup.sh it writes, and removing everything | Read below |
| Downloading and unpacking the kit inside Termux | Only the script itself was run |
Day to day. These use the files the script writes. On the phone the same dump and restore commands were run by hand; these exact lines were not:
ssh -p 8022 <phone> securevault/backup.sh > secure_vault-$(date +%F).sql.gz # from another device; then: gzip -t <file>
zcat <file> | mariadb --defaults-file=$HOME/securevault/my.cnf secure_vault # restore, on the phone
~/securevault/stop.sh # stop
Do not run termux.sh again while the server is running: it would start a second keep-alive loop.
Using the vault away from home
Use Tailscale (free for personal use): install it on the server and on every device, and sign in to the same account. Then:
- installer:
sudo securevault-server --tailscale(only Tailscale), or runsudo securevault-server --lanagain after installing Tailscale (home network and Tailscale; the app tries both addresses), - Docker: give the Tailscale address to
--init --address,
and connect each device again with the new line.
Do not forward port 3306 from your router to the internet, and do not put the server on a public address. The account names and usernames in the vault are not encrypted, and a database port on the internet is found and attacked within hours. The installer refuses a public address unless you pass --allow-public; this page does not recommend it.
TLS (installer only)
Tailscale already encrypts everything between your devices. On a home network the secret fields are encrypted before they leave the device, but names and usernames travel as they are; --tls encrypts the whole connection.
sudo securevault-server --tls # back: --no-tls
It makes a self-signed certificate and requires TLS from vault_user. Then:
- the app needs a version with a TLS switch on its server screen (it encrypts but does not verify the certificate). The app version without that switch cannot connect to a server that requires TLS;
- the agent module verifies the certificate: copy
ca.pem(the installer prints where it is) to the computer the agent module runs on and setSECURE_VAULT_DB_TLS_CAto its path.
Tested on Debian 12, Arch Linux and Fedora 45 with all three clients.
Backup
A backup is one compressed file. A backup that stays on the server does not survive the server: copy the files to another device or disk regularly.
| Installer | Docker | |
|---|---|---|
| Automatic | sudo securevault-backup --install-timer (or --backup-timer at install): every night between 03:15 and 03:30 in the machine's own time zone (date +%Z); systemctl list-timers securevault-backup.timer shows the next run | Always on: one a day |
| One now | sudo securevault-backup | docker compose run --rm backup --once |
| Where | /var/backups/securevault/ (root only) | ./backups/ in the kit folder |
| Kept | the newest 14 (--keep N) | the newest 14 |
Restore
Close the app on every device first. A restore replaces everything in the database; it saves the current state first (secure_vault-pre-restore-...; these safety copies are never deleted automatically) and asks you to type restore.
| Installer | Docker | |
|---|---|---|
| List | sudo securevault-restore | docker compose run --rm restore |
| Newest | sudo securevault-restore --latest | docker compose run --rm restore --latest |
| A file | sudo securevault-restore /path/file.sql.gz | put the file in ./backups/, then docker compose run --rm restore file.sql.gz |
vault_user and its password are not part of a backup; they belong to the server. So a backup can be restored on another server, and the devices then connect with that server's line. Moving a vault this way was tested from Debian 12 to Docker, from Arch to Debian 12 and from Docker to Arch.
Update
- MariaDB, installer: it is a normal package of your system; your usual system updates update it.
- MariaDB, Docker:
docker compose pull, thendocker compose up -d. The image is pinned to the 11.4 series. (No newer 11.4 image existed on the test day, sopullitself had nothing to do; starting the same data with a newer MariaDB image, 11.4 to 11.8, was tested and upgraded it in place.) - The kit: unpack the new kit and run
sudo ./install.shagain (it keeps your password and settings). For Docker, copy the new files over the old ones in your kit folder, keeping.envandbackups/, thendocker compose up -d.
Make a backup first.
Uninstall
Installer:
sudo securevault-server --uninstall # removes the setup, keeps the database
sudo securevault-server --uninstall --delete-data --remove-mariadb # removes everything
Without --delete-data your vault stays in MariaDB, and a MariaDB that the installer installed is left listening on the machine itself only. --remove-mariadb removes MariaDB and its data directory only if the installer installed it and no other database is left. Backups in /var/backups/securevault/ are never deleted. The small packages it may have installed besides MariaDB (nftables, qrencode, iproute2) stay.
Docker:
docker compose down # stops it; the data stays in the Docker volume
docker compose down -v # deletes the vault data for good
Then delete the kit folder if you no longer need .env and backups/.
Troubleshooting
These happened during testing, except the two entries that say "not tested".
The app or a MariaDB client says "SSL is required, but the server does not support it". A MariaDB command-line client of version 11.4 or newer insists on TLS by default. Add --skip-ssl to the client command. (The SecureVault app and agent module do not have this problem.)
The address in the connection details is wrong (a VPN address, for example). The installer takes the address of the network card your default route uses. If that is not the address your devices reach the machine at, name it: sudo securevault-server --address <IP> (listens on that address only) or add another with --extra-host <IP or name>.
"MariaDB did not come back after the restart" / the check at the end fails. Look at journalctl -u mariadb -n 30. Running the installer again with other options rewrites its settings even when MariaDB is down, so a wrong --address or --port can be repaired that way.
A device cannot connect, but securevault-server --check is fine. The check signs in from the server itself. From the device, test the port: nc -z -w 5 <address> 3306 (PowerShell: Test-NetConnection <address> -Port 3306). No answer means the network in between: the device is on another network (guest Wi-Fi, mobile data without Tailscale), or a firewall. With ufw or firewalld active the installer adds its rules there; --no-firewall skips them.
Fedora with SELinux, and a port other than 3306. Not tested (the tests ran in containers, where SELinux is off). SELinux lets MariaDB use port 3306 only; for another port you would need semanage port -a -t mysqld_port_t -p tcp <port>.
Docker: the database container keeps restarting, and its log says "Database is uninitialized and password option is not specified". There is no .env yet. Run docker compose run --rm setup --init --address <IP>, then docker compose up -d.
Docker: .env already exists. --init never overwrites it, because the passwords in it are the ones the database was created with. Changing a password in .env afterwards does not change it in the database.
Docker: a client on the same computer cannot reach the address. Use the address you gave to --init, not 127.0.0.1 or localhost: the port is published on that one address only.
Arch: "pacman could not install". The installer uses the package lists your system already has, and stops before changing anything when they are missing or old. Run sudo pacman -Syu first (in a script: --noconfirm); it upgrades the whole system.
sudo: securevault-server: command not found. Not tested: on Debian 12, Ubuntu 24.04 and Fedora 45 sudo found the command. Some systems leave /usr/local/sbin out of sudo's path; use the full path there: sudo /usr/local/sbin/securevault-server.