pyr0ball
5a4216952f
Git 2.35.2+ rejects repos where directory owner != current user, which is the common case when cloned as root into /opt. setup.sh now detects this and calls git config --global --add safe.directory automatically. When run via sudo, it writes into SUDO_USER's config rather than root's. README updated with both fixes: git safe.directory and chown for preflight.
174 lines
6 KiB
Markdown
174 lines
6 KiB
Markdown
# Peregrine
|
|
|
|
**AI-powered job search pipeline — by [Circuit Forge LLC](https://circuitforge.io)**
|
|
|
|
> *"Don't be evil, for real and forever."*
|
|
|
|
Automates the full job search lifecycle: discovery → matching → cover letters → applications → interview prep.
|
|
Privacy-first, local-first. Your data never leaves your machine.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
**1. Clone and install dependencies** (Docker, NVIDIA toolkit if needed):
|
|
|
|
```bash
|
|
git clone https://git.opensourcesolarpunk.com/pyr0ball/peregrine
|
|
cd peregrine
|
|
./manage.sh setup
|
|
```
|
|
|
|
**2. Start Peregrine:**
|
|
|
|
```bash
|
|
./manage.sh start # remote profile (API-only, no GPU)
|
|
./manage.sh start --profile cpu # local Ollama on CPU
|
|
./manage.sh start --profile single-gpu # Ollama + Vision on GPU 0
|
|
./manage.sh start --profile dual-gpu # Ollama + Vision + vLLM (GPU 0 + 1)
|
|
```
|
|
|
|
Or use `make` directly:
|
|
|
|
```bash
|
|
make start # remote profile
|
|
make start PROFILE=single-gpu
|
|
```
|
|
|
|
**3.** Open http://localhost:8501 — the setup wizard guides you through the rest.
|
|
|
|
> **macOS:** Docker Desktop must be running before starting.
|
|
> **Windows:** Not supported — use WSL2 with Ubuntu.
|
|
|
|
### Installing to `/opt` or other system directories
|
|
|
|
If you clone into a root-owned directory (e.g. `sudo git clone ... /opt/peregrine`), two things need fixing:
|
|
|
|
**1. Git ownership warning** (`fatal: detected dubious ownership`) — `./manage.sh setup` fixes this automatically. If you need git to work *before* running setup:
|
|
|
|
```bash
|
|
git config --global --add safe.directory /opt/peregrine
|
|
```
|
|
|
|
**2. Preflight write access** — preflight writes `.env` and `compose.override.yml` into the repo directory. Fix ownership once:
|
|
|
|
```bash
|
|
sudo chown -R $USER:$USER /opt/peregrine
|
|
```
|
|
|
|
After that, run everything without `sudo`.
|
|
|
|
### Podman
|
|
|
|
Podman is rootless by default — **no `sudo` needed.** `./manage.sh setup` will configure `podman-compose` if it isn't already present.
|
|
|
|
### Docker
|
|
|
|
After `./manage.sh setup`, log out and back in for docker group membership to take effect. Until then, prefix commands with `sudo`. After re-login, `sudo` is no longer required.
|
|
|
|
---
|
|
|
|
## Inference Profiles
|
|
|
|
| Profile | Services started | Use case |
|
|
|---------|-----------------|----------|
|
|
| `remote` | app + searxng | No GPU; LLM calls go to Anthropic / OpenAI |
|
|
| `cpu` | app + ollama + searxng | No GPU; local models on CPU (slow) |
|
|
| `single-gpu` | app + ollama + vision + searxng | One GPU: cover letters, research, vision |
|
|
| `dual-gpu` | app + ollama + vllm + vision + searxng | GPU 0 = Ollama, GPU 1 = vLLM |
|
|
|
|
---
|
|
|
|
## First-Run Wizard
|
|
|
|
On first launch the setup wizard walks through seven steps:
|
|
|
|
1. **Hardware** — detects NVIDIA GPUs and recommends a profile
|
|
2. **Tier** — choose free, paid, or premium (or use `dev_tier_override` for local testing)
|
|
3. **Identity** — name, email, phone, LinkedIn, career summary
|
|
4. **Resume** — upload a PDF/DOCX for LLM parsing, or use the guided form builder
|
|
5. **Inference** — configure LLM backends and API keys
|
|
6. **Search** — job titles, locations, boards, keywords, blocklist
|
|
7. **Integrations** — optional cloud storage, calendar, and notification services
|
|
|
|
Wizard state is saved after each step — a crash or browser close resumes where you left off.
|
|
Re-enter the wizard any time via **Settings → Developer → Reset wizard**.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
| Feature | Tier |
|
|
|---------|------|
|
|
| Job discovery (JobSpy + custom boards) | Free |
|
|
| Resume keyword matching | Free |
|
|
| Cover letter generation | Paid |
|
|
| Company research briefs | Paid |
|
|
| Interview prep & practice Q&A | Paid |
|
|
| Email sync & auto-classification | Paid |
|
|
| Survey assistant (culture-fit Q&A) | Paid |
|
|
| Integration connectors (Notion, Airtable, Google Sheets, etc.) | Paid |
|
|
| Calendar sync (Google, Apple) | Paid |
|
|
| Cover letter model fine-tuning | Premium |
|
|
| Multi-user support | Premium |
|
|
|
|
---
|
|
|
|
## Email Sync
|
|
|
|
Monitors your inbox for job-related emails and automatically updates job stages (interview requests, rejections, survey links, offers).
|
|
|
|
Configure in **Settings → Email**. Requires IMAP access and, for Gmail, an App Password.
|
|
|
|
---
|
|
|
|
## Integrations
|
|
|
|
Connect external services in **Settings → Integrations**:
|
|
|
|
- **Job tracking:** Notion, Airtable, Google Sheets
|
|
- **Document storage:** Google Drive, Dropbox, OneDrive, MEGA, Nextcloud
|
|
- **Calendar:** Google Calendar, Apple Calendar (CalDAV)
|
|
- **Notifications:** Slack, Discord (webhook), Home Assistant
|
|
|
|
---
|
|
|
|
## CLI Reference (`manage.sh`)
|
|
|
|
`manage.sh` is the single entry point for all common operations — no need to remember Make targets or Docker commands.
|
|
|
|
```
|
|
./manage.sh setup Install Docker/Podman + NVIDIA toolkit
|
|
./manage.sh start [--profile P] Preflight check then start services
|
|
./manage.sh stop Stop all services
|
|
./manage.sh restart Restart all services
|
|
./manage.sh status Show running containers
|
|
./manage.sh logs [service] Tail logs (default: app)
|
|
./manage.sh update Pull latest images + rebuild app container
|
|
./manage.sh preflight Check ports + resources; write .env
|
|
./manage.sh test Run test suite
|
|
./manage.sh prepare-training Scan docs for cover letters → training JSONL
|
|
./manage.sh finetune Run LoRA fine-tune (needs --profile single-gpu+)
|
|
./manage.sh open Open the web UI in your browser
|
|
./manage.sh clean Remove containers, images, volumes (asks to confirm)
|
|
```
|
|
|
|
---
|
|
|
|
## Developer Docs
|
|
|
|
Full documentation at: https://docs.circuitforge.io/peregrine
|
|
|
|
- [Installation guide](https://docs.circuitforge.io/peregrine/getting-started/installation/)
|
|
- [Adding a custom job board scraper](https://docs.circuitforge.io/peregrine/developer-guide/adding-scrapers/)
|
|
- [Adding an integration](https://docs.circuitforge.io/peregrine/developer-guide/adding-integrations/)
|
|
- [Contributing](https://docs.circuitforge.io/peregrine/developer-guide/contributing/)
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Core discovery pipeline: [MIT](LICENSE-MIT)
|
|
AI features (cover letter generation, company research, interview prep, UI): [BSL 1.1](LICENSE-BSL)
|
|
|
|
© 2026 Circuit Forge LLC
|