jobhunt-linkedin-helper 0.2.0

Standalone local fetch helper for hosted JobHunt — handles LinkedIn, Bayt, Indeed, and Glassdoor from your own IP

JobHunt Local Fetch Helper

jobhunt-linkedin-helper is the standalone local companion for hosted JobHunt deployments.

It keeps LinkedIn, Bayt, Indeed, and Glassdoor fetching on the user's own machine instead of the shared server IP, which makes the hosted product safer and more reliable.

What it does

• pairs with your hosted JobHunt server using a short-lived code
• stores only a revocable device token on disk
• starts the bundled LinkedIn scraper locally when needed
• runs Bayt / Indeed / Glassdoor fetches locally via JobSpy
• polls the server for local fetch tasks
• returns raw jobs back to JobHunt for normal scoring and deduping

Install

For end users (hosted JobHunt)

1. Download the .whl from your JobHunt admin or the project releases page.
2. Install it (Python 3.11+ required. Node.js 20+ is needed for LinkedIn support):

   uv tool install jobhunt-linkedin-helper.whl
   # or: pip install jobhunt-linkedin-helper.whl
   

3. Run it with your pairing code (see Run below).

The CLI bootstraps the bundled LinkedIn scraper automatically on first launch when LinkedIn support is needed — no separate node server.js step needed.

For local development (from this repo)

uv tool install ./linkedin-helper

Building a distributable wheel

cd linkedin-helper
./build.sh
# outputs dist/jobhunt_linkedin_helper-*.whl

Upload the wheel wherever you host downloads and set VITE_LINKEDIN_HELPER_DOWNLOAD_URL in your frontend .env.

Run

First pairing:

jobhunt-linkedin-helper \
  --server-url https://your-jobhunt-domain.com \
  --pairing-code JHLI-XXXX-XXXX

After pairing, the helper remembers its device token and future runs only need:

jobhunt-linkedin-helper --server-url https://your-jobhunt-domain.com

Notes

• The helper starts its own bundled LinkedIn scraper automatically. Users should not need a separate node server.js command.
• Bayt / Indeed / Glassdoor use JobSpy inside the same helper package.
• On first launch, the helper bootstraps its LinkedIn scraper dependencies with npm install if needed.
• If you only use Bayt / Indeed / Glassdoor, Python is enough. LinkedIn support still expects node and npm to be available on the local machine.

Options

Flag	Default	Description
--server-url	http://127.0.0.1:8000	Hosted JobHunt URL
--pairing-code	—	One-time code from the JobHunt UI
--device-name	hostname	Friendly device label shown in JobHunt
--token-file	~/.jobhunt/linkedin-local-agent.json	Where the helper stores its device token
--poll-seconds	8	How often to poll when idle
--once	off	Claim one task and exit
--scraper-port	3001	Port used by the helper-managed local scraper
--no-managed-scraper	off	Skip starting the bundled scraper and use --scraper-url instead
--scraper-url	http://127.0.0.1:3001	External scraper URL when --no-managed-scraper is used
--skip-scraper-bootstrap	off	Skip automatic npm install for advanced/dev usage