File Hunter

https://filehunter.zenlogic.uk/docs
Admin
File Hunter is a self-hosted web application for cataloging, searching, and deduplicating large...
Tokens:11,525
Snippets:129
Trust Score:4.5
Update:5 days ago
Show doc for...
Tokens:
Raw
### Start the agent with the binary

Source: https://filehunter.zenlogic.uk/docs/agents

Runs the agent using the compiled binary. This is the primary way to start the agent.

```bash
./filehunter-agent
```

--------------------------------

### launchd plist file content

Source: https://filehunter.zenlogic.uk/docs/installation

Paste this plist content into /Library/LaunchDaemons/uk.zenlogic.filehunter.plist. Adjust the username and paths to match your setup. The launcher starts both the server and the bundled local agent, so no separate agent service is needed.

```xml
<?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>
```

--------------------------------

### Enable and start the agent service

Source: https://filehunter.zenlogic.uk/docs/agents

Reloads systemd, enables the service to start on boot, and starts it immediately.

```bash
sudo systemctl daemon-reload
sudo systemctl enable filehunter-agent
sudo systemctl start filehunter-agent
```

--------------------------------

### systemd unit file content

Source: https://filehunter.zenlogic.uk/docs/installation

Paste this unit file content into /etc/systemd/system/filehunter.service. Adjust the user and paths to match your setup. The launcher starts both the server and the bundled local agent, so no separate agent service is needed.

```ini
[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
```

--------------------------------

### Clone and run the embedding service

Source: https://filehunter.zenlogic.uk/docs/embedding

Clones the repository and starts the service with ./embedding. The launch script creates a virtual environment, installs PyTorch with GPU support, downloads models, and starts the service. First run takes longer while models download. If GPU hardware changes, delete the venv directory and re-run.

```bash
git clone https://github.com/zen-logic/file-hunter-embedding.git
cd file-hunter-embedding
./embedding
```

--------------------------------

### Quick install with curl

Source: https://filehunter.zenlogic.uk/docs/installation

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

```bash
curl -fsSL https://filehunter.zenlogic.uk/install | bash
```

--------------------------------

### Install from source

Source: https://filehunter.zenlogic.uk/docs/installation

Clones the file-hunter and file-hunter-agent repositories, then runs the launcher from the file-hunter directory.

```bash
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
```

--------------------------------

### Start the agent with Python module

Source: https://filehunter.zenlogic.uk/docs/agents

Equivalent way to start the agent using the Python module. Useful when running from source or a virtual environment.

```bash
python -m file_hunter_agent
```

--------------------------------

### Load and start the launchd service

Source: https://filehunter.zenlogic.uk/docs/agents

Loads and starts the FileHunter agent launchd service using launchctl. Requires sudo.

```bash
sudo launchctl load /Library/LaunchDaemons/uk.zenlogic.filehunter-agent.plist
```

--------------------------------

### Enable and start File Hunter embedding service

Source: https://filehunter.zenlogic.uk/docs/embedding

Run these commands to reload systemd, enable the service to start on boot, and start it immediately.

```bash
sudo systemctl daemon-reload
sudo systemctl enable filehunter-embedding
sudo systemctl start filehunter-embedding
```

--------------------------------

### Start agent with server URL and token flags

Source: https://filehunter.zenlogic.uk/docs/agents

On first run, pass the server URL and token as flags instead of editing config.json. The values are saved automatically.

```bash
./filehunter-agent --server http://your-server:8000 --token <token>
```

--------------------------------

### Load the launchd service

Source: https://filehunter.zenlogic.uk/docs/embedding

Loads the plist file to start the service.

```bash
sudo launchctl load /Library/LaunchDaemons/uk.zenlogic.filehunter-embedding.plist
```

--------------------------------

### launchd plist configuration for FileHunter agent

Source: https://filehunter.zenlogic.uk/docs/agents

Plist configuration for the FileHunter agent launchd service. Adjust the path and username to match your setup. The service runs the Python module file_hunter_agent from the specified virtual environment, starts at load, and keeps alive. Logs are written to agent.log.

```xml
<?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-agent</string>
    <key>UserName</key>
    <string><your-username></string>
    <key>WorkingDirectory</key>
    <string>/Users/<your-username>/file-hunter-agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/<your-username>/file-hunter-agent/venv/bin/python</string>
        <string>-m</string>
        <string>file_hunter_agent</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/<your-username>/file-hunter-agent/agent.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/<your-username>/file-hunter-agent/agent.log</string>
</dict>
</plist>
```

--------------------------------

### Install LibreOffice on Debian/Ubuntu

Source: https://filehunter.zenlogic.uk/docs/embedding

Installs LibreOffice components without GUI for headless servers. Required for converting old binary Office formats (DOC, XLS, PPT).

```bash
sudo apt install libreoffice-writer-nogui libreoffice-calc-nogui libreoffice-impress-nogui
```

--------------------------------

### Check LibreOffice installation

Source: https://filehunter.zenlogic.uk/docs/embedding

Runs LibreOffice's command-line program to verify installation. The Linux command uses 'soffice --version', the macOS command uses the full path.

```bash
soffice --version                                              # Linux
/Applications/LibreOffice.app/Contents/MacOS/soffice --version  # macOS
```

--------------------------------

### Install File Hunter agent

Source: https://filehunter.zenlogic.uk/docs/agents

Clone the agent repository, create a virtual environment, and install dependencies. Use 'source venv/bin/activate' on macOS/Linux, or 'venv\Scripts\activate' on Windows.

```bash
git clone https://github.com/zen-logic/file-hunter-agent.git
cd file-hunter-agent
python -m venv venv
source venv/bin/activate   # on Windows: venv\Scripts\activate
pip install -r requirements.txt
```

--------------------------------

### Running File Hunter

Source: https://filehunter.zenlogic.uk/docs/installation

Runs the launcher from the extracted release directory. On first run, it prompts for host and port, creates a virtual environment, and installs dependencies.

```bash
cd filehunter-x.x.x
./filehunter
```

--------------------------------

### Install LibreOffice on macOS via Homebrew

Source: https://filehunter.zenlogic.uk/docs/embedding

Installs LibreOffice using Homebrew. Required for converting old binary Office formats on macOS.

```bash
brew install --cask libreoffice
```

--------------------------------

### Pull latest code and start embedding

Source: https://filehunter.zenlogic.uk/docs/embedding

Run these commands in the file-hunter-embedding folder after stopping the service to pull the latest code and start it again.

```bash
git pull
./embedding
```

--------------------------------

### Useful launchctl commands for service management

Source: https://filehunter.zenlogic.uk/docs/embedding

Commands to check status, stop, start, and follow logs for the service.

```bash
sudo launchctl list | grep filehunter-embedding              # check status
sudo launchctl unload /Library/LaunchDaemons/uk.zenlogic.filehunter-embedding.plist   # stop
sudo launchctl load /Library/LaunchDaemons/uk.zenlogic.filehunter-embedding.plist     # start
tail -f ~/file-hunter-embedding/embedding.log                # follow logs
```

--------------------------------

### Load launchd service

Source: https://filehunter.zenlogic.uk/docs/installation

Loads and starts the File Hunter launchd service.

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

--------------------------------

### Useful launchd commands

Source: https://filehunter.zenlogic.uk/docs/installation

Commands to check status, stop, start, and follow logs for the launchd service.

```bash
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
```

--------------------------------

### Systemd unit file for File Hunter Agent

Source: https://filehunter.zenlogic.uk/docs/agents

Paste this unit file into /etc/systemd/system/filehunter-agent.service. Adjust the User, WorkingDirectory, and ExecStart paths to match your setup.

```ini
[Unit]
Description=File Hunter Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=<your-user-name>
WorkingDirectory=/home/<your-user-name>/file-hunter-agent
ExecStart=/home/<your-user-name>/file-hunter-agent/venv/bin/python -m file_hunter_agent
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Upgrade agent: git pull, pip install, run

Source: https://filehunter.zenlogic.uk/docs/agents

Commands to upgrade the FileHunter agent by pulling the latest code, installing dependencies, and restarting the agent.

```bash
git pull
pip install -r requirements.txt
./filehunter-agent
```

--------------------------------

### Run embedding service with custom port

Source: https://filehunter.zenlogic.uk/docs/embedding

Starts the service with the --port option, overriding the config file's port setting. Command-line options override config file values.

```bash
./embedding --port 9000
```

--------------------------------

### systemd unit file for File Hunter embedding service

Source: https://filehunter.zenlogic.uk/docs/embedding

Paste this content into the unit file, adjusting the User, WorkingDirectory, and ExecStart paths to match your setup. The service runs the embedding binary and restarts on failure after 5 seconds.

```ini
[Unit]
Description=File Hunter Embedding Service
After=network.target

[Service]
Type=simple
User=<your-user-name>
WorkingDirectory=/home/<your-user-name>/file-hunter-embedding
ExecStart=/home/<your-user-name>/file-hunter-embedding/embedding
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Plist configuration for launchd service

Source: https://filehunter.zenlogic.uk/docs/embedding

Plist configuration for the launchd service. Adjust the path and username as needed. The service runs the embedding binary, starts at load, and keeps alive. Logs are written to embedding.log.

```xml
<?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-embedding</string>
    <key>UserName</key>
    <string><your-username></string>
    <key>WorkingDirectory</key>
    <string>/Users/<your-username>/file-hunter-embedding</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/<your-username>/file-hunter-embedding/embedding</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/<your-username>/file-hunter-embedding/embedding.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/<your-username>/file-hunter-embedding/embedding.log</string>
</dict>
</plist>
```

--------------------------------

### Useful launchctl commands for FileHunter agent

Source: https://filehunter.zenlogic.uk/docs/agents

Commands to check status, stop, start, and follow logs for the FileHunter agent service. The check status command filters for 'filehunter-agent' in the launchctl list output.

```bash
sudo launchctl list | grep filehunter-agent              # check status
sudo launchctl unload /Library/LaunchDaemons/uk.zenlogic.filehunter-agent.plist   # stop
sudo launchctl load /Library/LaunchDaemons/uk.zenlogic.filehunter-agent.plist     # start
tail -f ~/file-hunter-agent/agent.log                    # follow logs
```

--------------------------------

### Demo mode command

Source: https://filehunter.zenlogic.uk/docs/installation

Run with --demo to create a testdata/ directory with sample files and locations. Useful for exploring the UI before pointing it at real storage.

```bash
./filehunter --demo
```

--------------------------------

### Create plist file with nano

Source: https://filehunter.zenlogic.uk/docs/agents

Opens the nano editor to create the launchd plist file at /Library/LaunchDaemons/uk.zenlogic.filehunter-agent.plist. Requires sudo privileges.

```bash
sudo nano /Library/LaunchDaemons/uk.zenlogic.filehunter-agent.plist
```

--------------------------------

### Create plist file with sudo nano

Source: https://filehunter.zenlogic.uk/docs/embedding

Opens the plist file for editing in the LaunchDaemons directory. Adjust the path and username as needed.

```bash
sudo nano /Library/LaunchDaemons/uk.zenlogic.filehunter-embedding.plist
```

--------------------------------

### Create systemd unit file

Source: https://filehunter.zenlogic.uk/docs/agents

Opens a new unit file for the agent service. Use this to create the service definition.

```bash
sudo nano /etc/systemd/system/filehunter-agent.service
```

--------------------------------

### Create systemd unit file

Source: https://filehunter.zenlogic.uk/docs/installation

Opens a new unit file for the File Hunter service in the nano editor. Adjust the path and user as needed.

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

--------------------------------

### Create launchd plist file

Source: https://filehunter.zenlogic.uk/docs/installation

Opens a new plist file for the File Hunter launchd service in the nano editor. Adjust the path and username as needed.

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

--------------------------------

### Create systemd unit file for File Hunter embedding service

Source: https://filehunter.zenlogic.uk/docs/embedding

Run this command to create a new systemd unit file at /etc/systemd/system/filehunter-embedding.service. You will need to edit the file with the provided content.

```bash
sudo nano /etc/systemd/system/filehunter-embedding.service
```

--------------------------------

### Check status, follow logs, and restart agent service

Source: https://filehunter.zenlogic.uk/docs/agents

Useful commands for monitoring and managing the agent service: check status, follow logs, and restart after an update.

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

--------------------------------

### Useful systemd commands

Source: https://filehunter.zenlogic.uk/docs/installation

Commands to check service status, follow logs, and restart the service after an update.

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

--------------------------------

### Override HTTP bind address and port

Source: https://filehunter.zenlogic.uk/docs/agents

Use --host and --port to override the default HTTP bind address and port.

```bash
./filehunter-agent --host 0.0.0.0 --port 9001   # override HTTP bind address and port
```

--------------------------------

### Configure agent config.json

Source: https://filehunter.zenlogic.uk/docs/agents

Edit config.json in the agent directory to set the server URL, pairing token, HTTP bind address and port, and the locations to expose. Only listed paths are accessible.

```json
{
    "server_url": "http://your-server:8000",
    "token": "paste-your-token-here",
    "http_host": "0.0.0.0",
    "http_port": 8001,
    "locations": [
        {"name": "Photos", "path": "/mnt/photos"},
        {"name": "Music", "path": "/mnt/music"}
    ]
}
```

--------------------------------

### Useful systemd commands for File Hunter embedding service

Source: https://filehunter.zenlogic.uk/docs/embedding

These commands help check service status, follow logs, and restart the service after an update.

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

--------------------------------

### Restart filehunter-embedding service on Linux and macOS

Source: https://filehunter.zenlogic.uk/docs/embedding

If running as a service, restart it with these commands instead of running ./embedding. The Linux command uses systemctl, the macOS command uses launchctl.

```bash
sudo systemctl restart filehunter-embedding                                             # Linux
sudo launchctl kickstart -k system/uk.zenlogic.filehunter-embedding                      # macOS
```
Tokens:
Raw