Agents

A File Hunter agent is a lightweight service that runs on a remote machine and exposes its local filesystems to your central File Hunter server. The agent connects outbound to the server via WebSocket, so no port forwarding is needed on the agent side · it works through NAT and firewalls.

Agents require File Hunter Pro. The agent itself is free and open source.

Requirements

Python 3.11 or later
macOS, Linux, or Windows (WSL recommended on Windows)
A running File Hunter server with the Pro extension installed

Installation

Clone the repository and install:

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

Configuration

1. Register the agent on the server

In the File Hunter UI, go to Settings > Agents > Add Agent and copy the pairing token.

2. Configure the agent

Edit config.json in the agent directory:

{
    "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"}
    ]
}

server_url · the address of your File Hunter server
token · the pairing token from the server UI
http_host · bind address for the agent’s HTTP server (the server connects back to this for previews and downloads)
http_port · port for the agent’s HTTP server
locations · folders on this machine to expose to the catalog. Each needs a name (shown in the UI) and an absolute path. Only listed paths are accessible · the agent will not serve files outside configured roots

Running

Start the agent:

./filehunter-agent

Or equivalently:

python -m file_hunter_agent

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

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

The agent’s locations appear in the File Hunter navigation tree as soon as it connects. Scans, previews, and downloads all work through the UI exactly like local locations.

Command-line options

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

Running as a systemd service

These instructions are for remote agents running on separate machines. The local agent bundled with the server is managed automatically by the filehunter launcher · you do not need a separate service for it.

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

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

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

[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

Then enable and start it:

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

Useful commands:

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

Running as a macOS service (launchd)

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

sudo nano /Library/LaunchDaemons/uk.zenlogic.filehunter-agent.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-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>

Then load and start it:

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

Useful commands:

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

How it works

WebSocket (agent → server) · Registration, scan commands, and streaming scan results. The connection auto-reconnects if it drops.
HTTP (server → agent) · The server requests file content from the agent for previews and downloads. Authenticated with the same pairing token.

The agent has no database. All catalog data lives on the server. Agent locations behave like any other location · when the agent goes offline, its locations show an offline badge and the full catalog, file metadata, and hashes remain searchable and browsable until the agent reconnects.

Security

All HTTP endpoints on the agent require the pairing token via Authorization: Bearer header
File access is restricted to configured location roots · requests for paths outside those directories are rejected
The WebSocket connection is initiated by the agent, not the server · no inbound ports need to be opened on the agent machine

Upgrading

Pull the latest code and restart:

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