Installation

Requirements

• Python 3.10 or later
• macOS, Linux, or Windows (WSL recommended on Windows)

Quick install (macOS / Linux / WSL)

Downloads the latest release and extracts it into the current directory. Everything is self-contained · no files are installed outside the folder.

Or download the latest release manually from the releases page, extract it wherever you like, and run ./filehunter.

Docker

A community-maintained Docker image tracks releases and updates automatically. Setup instructions are in the project repo: github.com/ikidd/file-hunter-dockerized

Install from source

git clone https://github.com/zen-logic/file-hunter.git
git clone https://github.com/zen-logic/file-hunter-agent.git
cd file-hunter
./filehunter

Running

cd filehunter-x.x.x
./filehunter

On first run, the launcher prompts for host and port, creates a virtual environment, and installs dependencies. Then open the URL shown in your browser.

First run

When no users exist in the database, File Hunter shows a setup screen where you create the first user account. After logging in you’ll see the main interface with an empty catalog.

To get started, click + Add Location in the toolbar (or press N) to add your first location. Point it at any folder · a USB drive mount, a local directory, a network share · and start a scan.

Demo mode

Run with --demo to create a testdata/ directory with sample files and locations. This is useful for exploring the UI before pointing it at real storage. Delete testdata/ and the database files (file_hunter.db, hashes.db, stats.db) to reset.

Running as a systemd service

On Linux, you can run File Hunter as a background service that starts automatically on boot. Create a unit file:

sudo nano /etc/systemd/system/filehunter.service

Paste the following, adjusting paths and user to match your setup:

[Unit]
Description=File Hunter
After=network.target

[Service]
Type=simple
User=<your-user-name>
WorkingDirectory=/home/<your-user-name>/filehunter-x.x.x
ExecStart=/home/<your-user-name>/filehunter-x.x.x/filehunter
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

The launcher starts both the server and the bundled local agent. No separate agent service is needed on the server machine.

Then enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable filehunter
sudo systemctl start filehunter

Useful commands:

sudo systemctl status filehunter    # check status
sudo journalctl -u filehunter -f    # follow logs
sudo systemctl restart filehunter   # restart after update

Running as a macOS service (launchd)

On macOS, you can run File Hunter as a background service that starts automatically on boot. Create a plist file:

sudo nano /Library/LaunchDaemons/uk.zenlogic.filehunter.plist

Paste the following, adjusting the path and username to match your setup:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>uk.zenlogic.filehunter</string>
    <key>UserName</key>
    <string><your-username></string>
    <key>WorkingDirectory</key>
    <string>/Users/<your-username>/filehunter-x.x.x</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/<your-username>/filehunter-x.x.x/filehunter</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/<your-username>/filehunter-x.x.x/data/filehunter.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/<your-username>/filehunter-x.x.x/data/filehunter.log</string>
</dict>
</plist>

The launcher starts both the server and the bundled local agent. No separate agent service is needed on the server machine.

Then load and start it:

sudo launchctl load /Library/LaunchDaemons/uk.zenlogic.filehunter.plist

Useful commands:

sudo launchctl list | grep filehunter              # check status
sudo launchctl unload /Library/LaunchDaemons/uk.zenlogic.filehunter.plist   # stop
sudo launchctl load /Library/LaunchDaemons/uk.zenlogic.filehunter.plist     # start
tail -f ~/filehunter-x.x.x/data/filehunter.log    # follow logs

Upgrading

Download the latest release and extract it alongside the existing install. Copy your data/ directory and config.json into the new folder, then start with ./filehunter.

Database migrations are automatic · new columns and indexes are added on startup without data loss.

Installing Pro

After purchasing a Pro license, install it from within File Hunter:

1. Go to Settings (gear icon in the toolbar)
2. Click “Upgrade to Pro”
3. Enter your license key
4. The Pro package downloads and installs automatically
5. Click “Restart Now”

For air-gapped machines, download the package and use the “Upload package” option in the same dialog.