# Set up a SecureVault server: instructions for an AI agent You are an AI agent with a shell. Your human has asked you to set up their SecureVault server. Follow this page from top to bottom. It tells you what to look at, what to ask, the exact commands, how to read their result, and what you must never do. Server kit version: 1.0.0. ## 1. What you are setting up SecureVault is a password and 2FA vault. Its apps (phone, desktop) and its agent module keep the vault in a database that the owner hosts. That database is the whole server: - one MariaDB database named `secure_vault`, empty at first (the app creates its tables when it first connects), - one database user `vault_user` with a generated password and rights on that database only, - reachable on the owner's home network or over Tailscale, and from nowhere else. A finished server has four things, and you report each of them to the human as it stands (`ok` or `yes`, or `no`): | | What it means | | --- | --- | | **database** | it runs and `vault_user` can sign in over the network | | **starts after restart** | it comes back by itself when the machine restarts | | **firewall rule** | the database port answers private addresses only | | **nightly backup** | a backup is made every night without anyone doing anything | The kit tells you these four itself, in a status table (section 6). You never have to work them out, and you must not build your own replacement for one that is missing (no start script, no cron job, no firewall rule of your own). The human also needs one line, `securevault://connect?c=...`, to paste into the app. That line and the file `server.json` contain the database password; section 8 says how the human gets them without you seeing them. Secrets in the vault (passwords, 2FA keys, notes) are encrypted on the devices before they reach the database. Account names and usernames are not. That is why the database must stay on private networks. ## 2. Rules you must not break 1. **Never make the database reachable from the internet.** No port forwarding on a router, no cloud firewall rule, no `--allow-public`, no `0.0.0.0` as the Docker address. For use away from home the answer is Tailscale. (The installer's own `listen on: 0.0.0.0` in home-network mode is intended: its firewall rule and the account limit the port to private addresses, and it refuses to run that way on a machine with a public address. If the status table says `firewall rule no`, section 6 says what to do.) 2. **Never choose, shorten or replace the password.** The kit generates it (32 random letters and digits). Do not pass your own, do not edit it in `.env` or anywhere else. 3. **Never print a secret**, so that none lands in your transcript, a log or a file that gets committed: - Add `--hide-secrets` to every `install.sh`, `securevault-server` and `setup` command **you** run, all of them, so that you never have to judge which could print something. (Where there is nothing to hide it does nothing.) The commands on this page that you run have it. - `securevault-backup` and `securevault-restore` (in Docker: the `backup` and `restore` services) print no secret, only file names and sizes. They take no `--hide-secrets` and would reject it; run them as shown. - Every command that the installer or a helper **prints** is written for the human, in the form a person types in their own terminal. Do not run printed commands; use the ones on this page. - Do not run `--show`, `--print-secrets` or `docker compose run --rm qr`. A QR code is the password in another form. - Do not `cat`, `grep`, `head`, `jq` or open `server.json`, `connect.txt`, `.env` or `/etc/securevault/install.conf`, and never copy them into a project or repository folder. To check that such a file is there, `ls -l` or `stat` (name, owner, mode, size) is fine. - Moving a secret file to its place with `cp`, `scp` or a redirect into a file is fine: the content never appears on your screen. Use the commands of sections 7 and 8 exactly as written; they are built that way. 4. **Stop and ask if this machine already runs MariaDB or MySQL** (section 3 shows it). Do not pass `--use-existing-mariadb` on your own, and do not touch other databases or their settings. 5. **Run only the kit you verified.** Check the SHA-256 before unpacking. If it does not match, stop and tell the human. Do not edit the kit's scripts to get past an error; report the error instead. 6. **Do not accept a gap for the human.** `--manual-start` and `--no-firewall` give up one of the four things above. Pass them only after the human said yes to exactly that (sections 4 and 6 give you the question to ask). "Use this machine" or "just set it up" is not that yes. 7. **Never delete data on your own:** no `--uninstall`, `--delete-data`, `--reset-password`, `docker compose down -v` or restore unless the human asked for exactly that. 8. **Never ask the human for a password** (sudo, database, anything). If `sudo` needs a password you cannot give, ask the human to run that one command in their own terminal, and continue from its result. 9. **Do not install Tailscale or Docker, and do not change the router, yourself.** They need the human: a sign-in, a decision about a system-wide service, or a device you cannot reach. ## 3. Find out, then ask On this page `sudo` stands in front of every command that needs root. **If you are root, leave `sudo` out** (on a machine without sudo the commands fail otherwise). The same goes for commands you hand to the human: give them the form that works on that machine. The installer prints its own hints in the right form already. Run this on the machine that might host the server. Every line answers with an explicit value. The block contains no single quote, so it can be passed whole inside single quotes (`bash -c '...'`, `ssh HOST '...'`, `docker exec ... bash -c '...'`) or saved to a file and run with `bash`: ```sh echo "system: $(uname -s) $(uname -m), $( (. /etc/os-release 2>/dev/null && echo "$PRETTY_NAME") || echo "no /etc/os-release")" if [ "$(id -u)" = 0 ]; then echo "root: yes"; else echo "root: no"; fi if ! command -v sudo >/dev/null 2>&1; then echo "sudo: no"; elif sudo -n true 2>/dev/null; then echo "sudo: yes"; else echo "sudo: needs a password"; fi if [ -d /run/systemd/system ]; then echo "systemd: yes"; else echo "systemd: no"; fi if docker compose version >/dev/null 2>&1 && docker info >/dev/null 2>&1; then echo "docker: yes"; elif sudo -n docker info >/dev/null 2>&1; then echo "docker: yes, with sudo"; elif command -v docker >/dev/null 2>&1; then echo "docker: installed, but not running or not allowed for this user"; else echo "docker: no"; fi if grep -qsxE "cron|crond" /proc/[0-9]*/comm; then echo "cron: yes"; else echo "cron: no"; fi t=$(tailscale ip -4 2>/dev/null | head -n 1); echo "tailscale: ${t:-no}" R=""; [ "$(id -u)" = 0 ] || R="sudo -n" if $R test -f /etc/securevault/install.conf 2>/dev/null; then echo "securevault (installer) already here: yes"; else echo "securevault (installer) already here: no"; fi if docker compose ls 2>/dev/null | grep -qw securevault; then echo "securevault (docker) already here: yes"; else echo "securevault (docker) already here: no"; fi db=$(command -v mariadbd mysqld /usr/sbin/mariadbd /usr/libexec/mariadbd /usr/sbin/mysqld 2>/dev/null | head -n 1); echo "database server installed: ${db:-no}" if ! command -v ss >/dev/null 2>&1; then echo "port 3306 in use: unknown (no ss command)"; elif ss -ltn | grep -q ":3306 "; then echo "port 3306 in use: yes"; else echo "port 3306 in use: no"; fi a=$(ip -4 -brief addr 2>/dev/null || ifconfig 2>/dev/null | grep "inet " || hostname -I 2>/dev/null); echo "addresses:"; echo "${a:-unknown (no ip, ifconfig or hostname command)}" ``` (Windows has none of these commands: there the path is Docker; check `docker compose version` and `docker info`, and read the address from `ipconfig`.) What the answers mean: | Answer | What it leads to | | --- | --- | | `systemd: yes` | The installer (path A) can make the database start after a restart. | | `systemd: no` | Path A is **not** available, whatever else is installed. A `systemctl` command may exist anyway; only this test counts. Go by section 4. | | `docker: yes` / `yes, with sudo` | Path B is available (with `sudo` in front of every `docker` command in the second case). | | `docker: installed, but ...` / `no` | Path B is not available now. You do not install or start Docker (rule 9); section 4 says what to tell the human. | | `securevault ... already here: yes` | Do not set up a second one. Go to section 7 and check it. (The database server and the used port you then see are its own.) | | `database server installed: `, with no SecureVault here | Rule 4: stop and ask the human what it is for. The usual answer is path B, on another port if 3306 is in use (`--port 3307`). | | `port 3306 in use: yes` with no database server found | Something else uses the port: path B with `--port 3307`, or ask. | | `port 3306 in use: unknown` | Go on. If the port is taken after all, the set-up says so and stops. | | `addresses: unknown` | Ask the human for this machine's address on their network before choosing `--address`; the installer finds it by itself and shows it under `app tries:`. | | `sudo: needs a password` (and `root: no`) | Rule 8: the human runs the commands that need root. | | `cron: yes` / `no` | Matters only with `systemd: no`: it decides whether a nightly backup is possible there (section 4, line 5). | | `tailscale: 100.x.y.z` | Tailscale runs here; see the table in section 4. | Then ask the human only what you cannot see and they have not told you already: 1. **Which machine should host the vault?** It must be on whenever they want their passwords: a Raspberry Pi, a home server, an always-on PC. If they have only laptops, say so plainly and let them choose. 2. **Where do the devices that use the vault live?** Only at home on the same network, or also away from home? Away from home needs Tailscale on the server and on every device (free for personal use; the human installs it and signs in). 3. If you found more than one private address on the host: **which one do the other devices reach it at?** ## 4. Choose the path Take the first line that fits. There is one outcome per situation; do not mix them. | # | Situation | What you do | | --- | --- | --- | | 0 | A SecureVault server is already here | Set up nothing. Check it (section 7) and report. | | 1 | A database server is installed (and it is not SecureVault's own, line 0) and the human has not said what to do about it | Stop and ask (rule 4). | | 2 | `systemd: yes`, and the system is Debian, Ubuntu, Raspberry Pi OS, Arch Linux or Fedora | **Path A: the installer.** | | 3 | `docker: yes` (any system: macOS, Windows, any Linux) | **Path B: Docker.** | | 4 | An Android phone, and the human insists on it | **Path C: Termux.** Read the warning there first. | | 5 | Anything else | **This machine is not a suitable host as it is. Stop; install nothing, and do not fetch the kit yet.** Tell the human what is below. | For line 5, tell the human what you found (the lines from section 3) and that they have these choices. You carry out none of them without their answer: - **Another machine** that fits line 2 or 3. - **Docker on this machine.** They install it and make sure it starts with the computer (Docker Desktop on macOS and Windows; Docker Engine with the Compose plugin on Linux). You continue with path B once section 3 answers `docker: yes`. - Only if the system is one of the five in line 2 but has no systemd: **a server that somebody must start by hand after every restart of the machine.** Ask in these words: "This machine cannot start the database by itself. After every restart of the machine the vault stays unreachable until someone runs one command on it." and, by the `cron:` answer of section 3, either "There will also be no nightly backup: backups happen only when someone runs a command." (`cron: no`) or "The nightly backup will work only while cron is running on it." (`cron: yes`). Then: "Do you accept that?" Only after a yes, use path A with `--manual-start` added to the command. More questions for the human can still come up one at a time while you go on (section 6); ask each when it comes. Choose where it listens: | Situation | Installer | Docker (`--address`) | | --- | --- | --- | | Every device has Tailscale | `--tailscale` | the host's Tailscale address | | Home network only, or a mix | `--lan` (also listens on Tailscale when it is running on the host) | the host's home-network address | ## 5. Get the kit Keep it in a folder of its own, outside any project or repository. For Docker this folder stays: it will hold the settings and the backups. You need `curl` and `tar`. A minimal Debian or Ubuntu may lack curl: `sudo apt-get update && sudo apt-get install -y curl ca-certificates`. ```sh 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 \ && ls ``` The steps are chained on purpose: nothing is unpacked unless the checksum line answered `securevault-server-kit-1.0.0.tar.gz: OK`. If the chain stops there (`FAILED`, exit code not 0): rule 5. `ls` then shows `install.sh`, `docker-compose.yml`, `connect-info.sh`, `backup.sh`, `restore.sh`, `termux.sh`, `self-hosting.md`, `VERSION`, the folder `docker` and the archive itself. - macOS has no `sha256sum`: use `shasum -a 256 -c -` in its place. - Windows PowerShell (not tested; these are the equivalents): run the `mkdir` and the `cd` as two commands, use `curl.exe` instead of `curl`, compare `(Get-FileHash securevault-server-kit-1.0.0.tar.gz -Algorithm SHA256).Hash.ToLower()` with `4b4c37c675aad97595a976b6b5a4c1539efa40b2674d30f5f3e296173941265b` yourself, and unpack with the same `tar` line. Do not let anything convert the files' line endings. `self-hosting.md` in the kit is the full manual (options, update, uninstall, troubleshooting). Read it when something here does not fit. ## 6. Set up ### Path A: the installer It needs root: it installs MariaDB with the system's package manager and, where they are missing, three small packages: `iproute2` (to read the machine's addresses), `nftables` (the firewall rule) and `qrencode` (the QR code for the human). Each thing it installs gets its own `==> Installing ...` line. It writes one MariaDB settings file, adds a firewall rule for the port, and puts three commands in `/usr/local/sbin`. None of its steps waits for an answer when `--yes` is given. Three things about running it: - **Give it time.** It downloads packages; allow the command ten minutes before you call it stuck, and never start a second copy while one is running. - **Do not pipe it** through `tail`, `head`, `grep` or `tee`: you would get the exit code of that other program. Run it exactly as below; if you need less output, read the last 15 lines of what you already have. - **Do not run what it prints.** Its output ends with commands for the human (`--show`, `--check`, the backup command) in the form a person types. Yours are on this page. ```sh cd ~/securevault-server sudo ./install.sh --lan --backup-timer --hide-secrets --yes; echo "exit code: $?" ``` Use `--tailscale` instead of `--lan` if section 4 says so. Add `--manual-start` only in the case of section 4, line 5, after the human's yes. `--manual-start` and `--no-firewall` are remembered: later runs on that machine keep them without being told again. **How to read the result.** Do not go by the last line of text or by a sample. Go by these two things, which are the same on every system: 1. the exit code, and 2. the line that starts with `RESULT:` together with the status table above it. | Exit code | The run printed | Meaning | What you do | | --- | --- | --- | --- | | 0 | `RESULT: complete` | All four things are in place. | Go on to section 7. | | 0 | `RESULT: set up, but without: ...` | Nothing unexpected is missing, but this is not a full server. The things after "without" were switched off on purpose (`--no-firewall`), given up with `--manual-start` (start after a restart, and the nightly backup where nothing can run it), or not asked for. | Go on, and tell the human each `no` row of the table. | | 3 | `RESULT: incomplete: ...`, sometimes followed by `(and without: ...)` | The database is set up, but the things named after "incomplete:" were asked for and are missing. (Those after "without" are as in the row above.) | Read the `no` rows. Do not work around them. See "When a row says no" below. | | 1 | a line starting with `ERROR:` and no `RESULT:` line | It stopped there. The message says why and whether anything was changed. | See "When it stops with ERROR" below. | Lines starting with `WARNING:` are information; the run goes on. An `ERROR:` line always comes with exit code 1. In the table the first row answers `ok` or `no`, the other three `yes` or `no`. The end of a complete run looks like this (an example from Debian 12: the steps above it, the package names and the addresses differ from system to system, and Arch has one step more): ``` ==> Check: vault_user signs in over the network ok 172.30.77.10:3306 accepts vault_user SecureVault server: connection details Server addresses: 172.30.77.10 (the app tries them in this order) Port: 3306 Database: secure_vault User: vault_user Password: (not printed) TLS: off The password and the securevault://connect line were not printed here (this output is not a terminal, or --hide-secrets was given). They are in: /etc/securevault/server.json (server.json, for copying to a device) /etc/securevault/connect.txt (the line to paste into the app) To see them, with a QR code for a phone, a person runs in their own terminal: sudo /usr/local/sbin/securevault-server --show Check it any time: sudo /usr/local/sbin/securevault-server --check Back up now: sudo /usr/local/sbin/securevault-backup Away from home: install Tailscale on this server and your devices, then: sudo /usr/local/sbin/securevault-server --lan Keep the address: give this machine a fixed address in your router (a DHCP reservation); the app is told the address above and loses the server if it changes. 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 ``` The commands in that output are printed in the form that works on that machine (with `sudo` only where sudo exists). The `--show` command is for the human (section 8), not for you. Also check one thing the installer cannot know: **`Server addresses:` must be the address the other devices reach this machine at** (the one from section 3). On a machine with a VPN it can be wrong; then run the same command again with `--address ` in place of `--lan`. And tell the human the "Keep the address" advice: the app is given that address, so the router should always hand this machine the same one. **When a row says no** | Row | Why | What you do | | --- | --- | --- | | `starts after restart no` | There is no systemd. You only get here with `--manual-start`. | Tell the human the command in that row (`securevault-server --start`): someone must run it after every restart of the machine. Do not write a start script or a service yourself. | | `firewall rule no` (could not be added) | The system refused the rule, for example `Operation not permitted` in a container or on a restricted virtual server. | The port now answers every machine that can reach this one; only the account's limit to private addresses guards it. Tell the human that sentence and the reason in the row. Their choices: remove the cause and run the same command again, move to another machine, or accept it. The row itself mentions `--no-firewall`; that is the human's choice, not yours (rule 6). Only after their yes to accepting it, run the same command again with `--no-firewall` added; `firewall rule` is then among the things named after "without". Do not add firewall rules of your own. | | `nightly backup no` | The row gives the reason: nothing on this system can run it (no systemd, no running cron), or it was not turned on. | Tell the human that backups happen only when someone runs the command in that row. Do not set up a scheduler yourself. | | `database no` | The sign-in check failed; the lines above the table say on which address and why. | Read `self-hosting.md`, "Troubleshooting". Running the same command again is safe. | **When it stops with ERROR** Read the message: it says what to do, and running the command again later finishes whatever was begun. Messages you may see and must not work around: - `this system does not run systemd ... Nothing was changed` → section 4, line 5. - `MariaDB is already installed here and used by something else` → rule 4: stop and ask. - `Oracle MySQL is installed here` → path B, after asking (rule 4). - `this machine also has a public internet address` or `is not a private home-network address` → use `--tailscale`. - `Tailscale is not running here` → the human installs and signs in to Tailscale first, or you use `--lan`. - `pacman could not install ... Nothing was changed` (Arch) → the package lists are missing or old. You do not need to check for this beforehand: the installer finds out before it changes anything. The fix upgrades the whole system, so ask the human first unless they already said yes: `sudo pacman -Syu --noconfirm` (without `--noconfirm` it waits for an answer). Then run the installer again. Do not run `pacman -Sy` alone, although pacman's own message under the error suggests it: Arch does not support installing from fresh lists onto an old system. ### Path B: Docker Everything is a `docker compose` command with nothing in it that belongs to one shell. (They were run in bash on Linux only; PowerShell and zsh were not tested.) Put `sudo` in front of `docker` if section 3 said `docker: yes, with sudo`. Use the host's address from section 3 (not `127.0.0.1`, not `0.0.0.0`). None of these commands waits for an answer. ```sh cd ~/securevault-server docker compose run --rm setup --init --hide-secrets --address 192.168.1.20 # once; add --port 3307 if 3306 is taken docker compose up -d docker compose run --rm setup --hide-secrets ``` Each must exit with 0. The first answers `Wrote .env (in the kit folder): the database will listen on
port .` The third prints the connection details with `Password: (not printed)`. Then wait until the database is ready, and check it: ```sh docker compose ps # the db container must say "(healthy)", the backup container "Up" docker compose logs db | grep "SecureVault:" ``` The second must print `SecureVault: vault_user is limited to the secure_vault database and to private networks`. If the database container is not `(healthy)` after a minute, look at `docker compose logs db`. The four things, in the Docker path: | | | | --- | --- | | database | `(healthy)` above, and the port test of section 7 | | starts after restart | yes only if Docker itself starts with the computer: the containers have the restart policy `unless-stopped`. Linux: `systemctl is-enabled docker.service` must answer `enabled`. If it answers `disabled`, Docker starts only when someone first uses it, and the vault stays down after a restart until then: report this row as **no** and tell the human the fix, `sudo systemctl enable docker.service` (their decision; not tested here). Docker Desktop: its "start when you sign in" setting, which the human checks | | firewall rule | **none**: the limit is that the port is published on the one address you gave. Never give `0.0.0.0` | | nightly backup | yes: the `backup` container writes one a day into `backups/` in the kit folder | - `--init` refuses an address that is not private, and refuses to overwrite an existing `.env`. Do not delete `.env` to get past that: it holds the passwords the database was created with. - If the database container keeps restarting with `Database is uninitialized and password option is not specified`, `.env` is missing: run the `--init` line, then `docker compose up -d` again. - **macOS and Windows (Docker Desktop) were not tested.** The commands are the ones tested on Linux. If a device cannot connect there, the first suspect is the operating system's firewall blocking incoming connections to the port; tell the human rather than switching the firewall off. - **On Linux too, the Docker server was only reached from the same computer** (other containers and programs on it), never from a second machine over a home network. So the port test from a second machine in section 7 is not a formality here: do it. - Tell the human to give this computer a fixed address in the router (a DHCP reservation): the app is given the address, and loses the server if it changes. ### Path C: an Android phone (Termux) Only if the human asks for it. It worked in one test on one phone, but start after a reboot, Termux being swiped away and an unplugged sleeping phone were not tested, and it needs Tailscale on every device. Read "Android phone (Termux)" in `self-hosting.md` to the human before starting, and let them decide. The human does the steps on the phone (Tailscale app, Termux from F-Droid, Termux:Boot opened once, battery set to unrestricted). In Termux, with the kit unpacked: ```sh pkg install -y mariadb bash termux.sh ``` It must exit with 0 and its last line names the two files: `SecureVault database is running on 100.x.y.z:3306. Connection details: .../securevault/server.json, paste line: .../securevault/connect.txt`. Do not run `termux.sh` a second time while it is running. This path prints no status table; report the four things from `self-hosting.md`: restart not tested, no firewall, no automatic backup. ## 7. Verify ### On the server Path A: ```sh sudo securevault-server --check --hide-secrets; echo "exit code: $?" ``` It signs in as `vault_user` over each network address and prints the same status table and `RESULT:` line as the installer; read them the same way (exit code 0 or 3). The `database` row also gives the MariaDB version for your report. If the command is not found, use the full path `/usr/local/sbin/securevault-server`. Do not restart the machine to prove "starts after restart" unless the human agrees; the table's row is the answer. Path B: ```sh docker compose ps docker compose exec db mariadb --version # the version is the number in front of "-MariaDB" ``` ### Only on a machine installed with `--manual-start` Skip this part on every other machine. Here it is how the database comes back after a restart of the machine, and the command the human needs: ```sh sudo securevault-server --start --hide-secrets; echo "exit code: $?" ``` It starts the database, loads the firewall rule again and prints the table. Nothing else does this on such a machine. Run it once now: while the database is running it says so and only checks, which shows the human's command is there and works. Do not stop the database to try a real start unless the human agrees. ### From a second machine: does the port answer? Run this on another machine on the same network (or the same Tailscale network), with the address and port from the connection details. It picks a method that exists there and always answers with one line: ```sh A=192.168.1.20; P=3306 if command -v timeout >/dev/null 2>&1 && command -v bash >/dev/null 2>&1; then timeout 5 bash -c "/dev/null && echo "port: open" || echo "port: no answer"; elif command -v nc >/dev/null 2>&1; then nc -z -w 5 "$A" "$P" 2>/dev/null && echo "port: open" || echo "port: no answer"; else echo "port: cannot test (no bash with timeout, no nc)"; fi ``` Windows PowerShell: `Test-NetConnection 192.168.1.20 -Port 3306` must show `TcpTestSucceeded : True`. - `port: open` shows that the port answers, not that a sign-in works; the server's own check above and the app's **Test connection** show that. - `port: no answer`, while the server's own check passes, means the network in between: the machines are on different networks (guest Wi-Fi, a VPN), or a firewall. Do not open anything wider to fix it; find which. - `port: cannot test`, or no second machine: say in your report that this test was not done. The opposite test is one for the human: a phone on mobile data without Tailscale must get no answer. (Every machine on a private network is allowed in, so you cannot run this one from the home network.) ### A full sign-in from a second machine: only if `server.json` is already there **In a normal run you skip this**, and say so in your report: it needs `server.json` on the second machine, and the file gets there only when the human asked for the file-to-file hand-over of section 8. Do not copy the file just to run this test. The proof of a sign-in from another device is the app's **Test connection**. If the file is there, this prints `sign-in ok` and never the password. The lines contain single quotes: save them to a file and run it with `bash`, do not retype them inside other quotes. First make a client settings file from `server.json` without showing it, with whichever of the two the machine has: ```sh f="$HOME/.config/securevault/server.json"; d=$(mktemp -d); chmod 700 "$d" # with Python 3: python3 -c 'import json,os,sys; c=json.load(open(sys.argv[1])); os.write(os.open(sys.argv[2],os.O_WRONLY|os.O_CREAT,0o600),("[client]\nhost=%s\nport=%d\ndatabase=%s\nuser=%s\npassword=%s\n"%(c["hosts"][0],c["port"],c["database"],c["user"],c["password"])).encode())' "$f" "$d/c.cnf" # or with GNU sed (Linux), when the file is as the kit wrote it: (umask 077; sed -E 's/.*"hosts":\["([^"]+)".*"port":([0-9]+).*"database":"([^"]+)","user":"([^"]+)","password":"([^"]+)".*/[client]\nhost=\1\nport=\2\ndatabase=\3\nuser=\4\npassword=\5/' "$f" > "$d/c.cnf") grep -c '^password=' "$d/c.cnf" # must print 1; it prints a count, not the password ``` Then sign in, with whichever client the machine has, and remove the file: ```sh mariadb --defaults-extra-file="$d/c.cnf" --skip-ssl -N -e "SELECT 'sign-in ok'" # the mariadb client docker run --rm --network host -v "$d/c.cnf:/c.cnf:ro" --entrypoint mariadb mariadb:11.4 --defaults-extra-file=/c.cnf --skip-ssl -N -e "SELECT 'sign-in ok'" # or Docker rm -rf "$d" ``` Do not install a client or Python for this test without asking, and do not replace these lines with something that reads `server.json` onto your screen. ## 8. Hand the connection to the human The human needs the `securevault://connect?c=...` line (to paste into the app) or its QR code (to scan with the phone app). You must not see either. Two ways; use the first unless the human asks for the second. **The human looks, in their own terminal.** Tell them to run this themselves, not through you. The files are owned by root and closed to everyone else, so the human needs root for it: | Path | What the human types | | --- | --- | | A, machine with sudo | `sudo securevault-server --show` | | A, machine without sudo (section 3 said `sudo: no`) | first become root (log in as root, or `su -`), then `securevault-server --show` | | B | in the kit folder: `docker compose run --rm setup` (the line) and `docker compose run --rm qr` (the QR code); with `sudo` in front where Docker needs it | | C | on the phone: `cat ~/securevault/connect.txt` | It shows the connection details, the line and, where `qrencode` could be installed, a QR code. Then, in the app: **Connect to your server** → **Paste link** (or **Scan QR** on a phone) → **Test connection** → **Continue**. **File to file, for a desktop that runs the agent module, and only when the human asks for it.** The agent module reads the settings from `server.json` in the user's configuration folder (Linux: `~/.config/securevault/server.json`, mode 600; macOS: `~/Library/Application Support/SecureVault/server.json`; Windows: `%APPDATA%\SecureVault\server.json`). Put the file there without displaying it, with the one line that fits: ```sh mkdir -p ~/.config/securevault && chmod 700 ~/.config/securevault sudo ./install.sh --hide-secrets --yes --json-out "$HOME/.config/securevault/server.json" # path A, server = this machine cp -p server.json ~/.config/securevault/server.json # path B, server = this machine (umask 077; ssh -o BatchMode=yes USER@SERVER "sudo -n cat /etc/securevault/server.json" > ~/.config/securevault/server.json) # path A, server elsewhere, with sudo there (umask 077; ssh -o BatchMode=yes root@SERVER "cat /etc/securevault/server.json" > ~/.config/securevault/server.json) # path A, server elsewhere, no sudo there: sign in as root ``` Keep the redirect and the `--json-out` exactly as written: without them the file's content would be printed. (`BatchMode` and `sudo -n` make the ssh lines fail at once instead of waiting for a password; if one fails, the human copies the file. The two ssh lines were not tested over ssh.) The local lines were tested with the agent module's settings reader. Whether the app also picks up a file placed this way without showing its connect screen was not tested; if the app still asks, the human pastes the line. ## 9. Backups - Path A: the status table's `nightly backup` row is the answer. With `yes`, it runs every night between 03:15 and 03:30 in the server's own time zone. Find that zone with `date +%Z` on the server and put both in your report ("backups run between 03:15 and 03:30 UTC", for example); the human judges whether that suits them. With `no`, the command below is the only way a backup gets made; say so to the human. In both cases you make the first one now (it prints a file name and a size, no secret, and takes no `--hide-secrets`): `sudo securevault-backup` → `Backup written: /var/backups/securevault/secure_vault--