Partner Handbook

For IT partners who install and look after HARBOUR for their clients. Version 1.3.29, October 2026.

HARBOUR is a private AI workspace that runs entirely on the client's own hardware. This handbook covers what your engineers need day to day: installing it, checking it, backing it up, rebuilding it on a replacement machine, updating it, and when to call us.

Who does what (full detail in the support policy):

1. Where HARBOUR keeps things

Everything that belongs to the client lives in one folder:

Inside it: the database (harbour-ai.db: accounts, conversations, memories, settings, audit log), uploads/ and kb/ (documents), rag/ (the document-search index), the licence (licence.json), the keys that unlock saved credentials (trust-root.key, vault.key.enc), backups/, and the logs (harbour-ai.log, backend-startup.log).

The AI models HARBOUR talks to are not in that folder. They belong to Ollama, which keeps them in ~/.ollama/models (Linux desktop install, per user), /usr/share/ollama/.ollama/models (Linux system service), C:\Users\<name>\.ollama\models (Windows), or the ollama-models Docker volume.

2. Installing

Desktop (Linux or Windows)

1. Install Ollama from ollama.com and pull the models the client will use, for example ollama pull llama3.1. Model downloads need internet. For an office without it, pull them in your workshop, or copy a models folder from another machine (§6).
2. Install HARBOUR from the releases page:
   • Windows: HARBOUR-AI-Setup.exe (installed) or HARBOUR-AI-Portable.exe.
   • Linux: HARBOUR-AI.AppImage (chmod +x, then run it; on older systems sudo apt install libfuse2) or HARBOUR-AI.deb (sudo apt install ./HARBOUR-AI.deb).
3. Start it. The first screen asks for the licence key. Activation checks the key with HARBOUR's licence server once, so it needs internet the first time. For an offline site, activate in your workshop before the machine is delivered. A key activated on one machine is refused on a second one. To move a client to new hardware, restore a backup (§5) instead of activating again: the licence comes back with it.
4. Create the first account. The first account becomes the administrator.
5. The setup wizard asks what the firm does, how replies should be written, and for a few first documents. That goes into memory and the Company Knowledge Base for everyone at the firm. It can be skipped and changed later.
6. Make a second administrator straight away (⚙ SYSTEM → Admin → Users → Set role → admin), so one forgotten password never locks the firm out.
7. Set up backups (§4).

Docker / server

See DOCKER.md. In short: set JWT_SECRET, LICENCE_KEY, LICENCE_TIER, ADMIN_EMAIL and ADMIN_PASSWORD in .env, then docker compose up -d. The admin account is created on first start. Staff reach HARBOUR in a browser at http://<server>:8000. For an office network, put it behind the nginx/TLS configuration in docker-compose.prod.yml. Set HARBOUR_APPLIANCE_MODE=true if only the administrator should create accounts.

Power cuts (UPS)

Every HARBOUR machine should be on a UPS, so a power cut doesn't take it down mid-write. On a tower that has no redundant power supply, the UPS is the standard answer. The UPS isn't there to keep HARBOUR running through a long cut. Its job is to give the machine time to shut itself down cleanly.

HARBOUR doesn't talk to the UPS itself. The operating system shuts the machine down, and HARBOUR stops cleanly as part of that.

• Linux: install Network UPS Tools (sudo apt install nut) and set it to shut the machine down when the UPS reports a low battery. APC Smart-UPS and Eaton 5P/5PX units work with it over USB. upsc <ups-name> should show the UPS's status and charge.
• Windows: use the UPS maker's shutdown software.
• BIOS: set the machine to power on when mains power returns. The Docker server restarts HARBOUR and Ollama automatically when the machine starts (restart: unless-stopped).

Test it at handover. Pull the UPS's mains plug and check that the machine shuts itself down before the battery runs out. Then plug it back in and check that the machine and HARBOUR come back up without anyone touching them. UPS batteries usually need replacing every three to five years, so add that to the client's maintenance schedule and turn on the UPS's self-test.

Features that face the outside world

Four features only work if people outside the office can reach HARBOUR. Everything else should stay on the office network.

Publish only those paths, over HTTPS, through a reverse proxy, and nothing else. The embed snippet and the Twilio webhook address shown in HARBOUR use the address staff open HARBOUR on, so if that is a private one, give the client the public address instead.

3. Routine checks

Weekly, or after any change to the machine:

For monitoring tools, GET /health returns 200 when the engine is up.

4. Backups

A backup is the whole installation: accounts, conversations, documents, the search index, settings, the licence and the keys to saved logins. HARBOUR takes one every night at 03:30. If the machine was off at that time, it takes one about ten minutes after it next starts.

Set it up once, in ⚙ SYSTEM → Diagnostics → Backups & restore:

1. Encryption: set a passphrase of at least 10 characters. Write it down and keep it away from the machine, in the client's safe or your password manager. An encrypted backup can't be restored without it, by anyone, including HARBOUR's developer.
2. Second copy: enter a folder on a USB drive, a second disk, or a network share the operating system has mounted. Every backup is copied there and read back to check the copy. For an off-site copy, use two USB drives and swap them weekly, with one always off-site. Docker: the folder must be visible inside the container. Mount it as a volume, e.g. - /mnt/usb/harbour-backups:/second-copy, and enter /second-copy.
3. Keep: how many backups to keep in each place (default 10).
4. Press BACK UP NOW and check the status line says the second copy was made.

The status line shows the last backup and the last second copy, and says FAILED with the reason when one goes wrong (for example "isn't available… check it's plugged in"). Check it as part of §3.

AI models are not in the backup unless "Include downloaded voice and search models" is ticked, and Ollama's language models never are. See §6.

5. Replacing a machine (restore)

Use this when a machine fails, is stolen, or is being upgraded. No internet is needed, and neither is HARBOUR's developer.

1. Install HARBOUR on the new machine (§2 steps 1–2). Do not activate a licence key.
2. Start HARBOUR:
   • Desktop: on the licence screen choose "Moving to a new computer? Restore from a backup", pick the backup file (from the USB drive), and enter the passphrase.
   • Browser / Docker: on the sign-in screen of a new installation choose "MOVING TO A NEW MACHINE? RESTORE FROM A BACKUP". If ADMIN_EMAIL created an account on first start, sign in with it instead and use Backups & restore → Restore from a file.
3. HARBOUR checks every file in the backup against its checksum before changing anything. A wrong passphrase, a damaged file or a copy that didn't finish is refused, and nothing is touched.
4. Restart to finish: the desktop app restarts itself; for Docker run docker restart harbour-ai.
5. Sign in with the client's usual accounts. Conversations, documents, memories, settings, the licence and saved logins are back.
6. Copy the Ollama models across if the new machine doesn't have them (§6), then run the self-test.

Whatever was on the machine before the restore is moved to a pre-restore-<date> folder in the data folder, not deleted. Delete it once you're happy.

Measured: with 2 GB of documents, the new machine was restored and signed in 45 seconds after it was first started, with no network (§10).

The same restore works on the existing machine to undo a mistake: Backups & restore → pick a backup → Restore.

Test a restore every quarter, on a spare machine or a virtual machine. A backup nobody has restored is a hope, not a backup.

6. Moving AI models without internet

Ollama's models can be copied between machines. With Ollama stopped, copy the whole models folder (§1) from a machine that has them onto the new one, in the same place, then start Ollama. ollama list should show them. For Docker, copy into the ollama-models volume.

Voice transcription (Whisper) downloads its model the first time someone uses dictation. On an offline site, use dictation once in the workshop before delivery, or tick "Include downloaded voice and search models" before taking the backup you restore from.

7. Updates

Each machine's setting is in ⚙ SYSTEM → Diagnostics → Software updates:

• Automatically, from HARBOUR's releases: needs internet. New versions download in the background and install on the next restart.
• From an update folder on this network: for offline sites, or if you approve versions first. Put the release files in a folder served over HTTP on the office network: the feed file (latest-linux.yml for Linux, latest.yml for Windows) and the versioned installer it names, e.g. HARBOUR-AI-1.3.29.AppImage or HARBOUR-AI-1.3.29-Setup.exe, exactly as named on the releases page. Enter the folder's address. To pin it on a machine image, set HARBOUR_UPDATE_SERVER=http://…/ instead.
• Never: install new versions by hand, by running the new installer (data is kept). To pin it, set HARBOUR_AUTO_UPDATE=0.

The setting takes effect the next time HARBOUR starts. Docker has no auto-updater: load the new image and run docker compose up -d. Data is in the volume and is kept.

What changed in each release is in the release notes on the releases page. A security fix is said to be one in its release notes. Install those promptly on offline machines, because nothing else will.

8. Users and passwords

• Add users: ⚙ SYSTEM → Admin → Users → ADD A USER.
• A user forgot their password: ⚙ SYSTEM → Admin → Users → Reset password.
• Make someone an administrator: Admin → Users → Set role → admin. HARBOUR won't remove the last administrator.
• The administrator is locked out: on the machine HARBOUR runs on, open the sign-in screen → "Forgotten the administrator password?" → CREATE A RECOVERY CODE. HARBOUR writes a one-time code to recovery-token.txt in the data folder. Open that file, paste the code, and set a new password. The code works once, lasts 15 minutes, and is refused from any other machine. Being able to open that folder is the proof of ownership.

9. When something is wrong

1. Run the self-test (§3). Most problems are named there with the fix.
2. Common causes: Ollama not running (ollama list), the machine short of disk space, a second-copy drive unplugged, a model too large for the machine's memory.
3. Logs are in the data folder: harbour-ai.log (the engine) and backend-startup.log (start-up, including restores).
4. If it is a HARBOUR fault, escalate: email Gregorymoores@proton.me with what happened, what you have tried, the version, and the support bundle (Self-test → download). The bundle masks keys, email addresses and home folders and is shown to you first. Read it before sending.
5. Security (a suspected vulnerability or compromise): email at once with the subject SECURITY, any day, and never in a public issue.

10. Measured, not promised