One search box โ every job board. Good Jobs is a self-hosted job search aggregator that scrapes recently posted jobs from 21 sources and streams results to your browser in real time over SSE โ with AI-powered intent detection, skill extraction, vector-based related-job supplements, and a permanent Redis cache warmed every 2 hours.
๐ป๐ณ Vietnam is the core market โ LinkedIn, ITViec, TopCV, VietnamWorks, CareerViet, TopDev, JobsGo, CareerLink, Glints, ViecOi, Indeed, TechJobs, Xรณm Jobs. ๐ Opt-in global mode covers the US, UK, and Singapore โ LinkedIn, Indeed, RemoteOK, We Work Remotely, Glassdoor, USAJOBS, Dice. Just type the city; the country is inferred automatically ("nyc" โ New York โ US sources).
| Date | Feature |
|---|---|
| 2026-11-17 | LinkedIn auto-posting โ each published news article is posted automatically to the Good Jobs company page via the LinkedIn REST API (Community Management API, w_organization_social) |
| 2026-11-07 | News desk, homepage filters & All Jobs browser โ goodjobs.io.vn/news publishes AI-generated Vietnamese articles twice a day (Workers AI + D1, RSS, news sitemap); the homepage feed merges the live Redis cache with the durable Cloudflare D1 archive so every job ever scraped stays browsable, with category/location/source filters and a jobs-per-page selector |
| 2026-10-03 | MCP server & career-ops submodule โ mcp/goodjobs_mcp.py exposes search, recent jobs, semantic search, keyword classification, city normalization, and cache status as read-only tools for MCP clients such as Claude Desktop and Claude Code; career-ops (branch feat/goodjobs-provider) vendored at thirdparty/career-ops with the goodjobs provider tests |
| 2026-08-30 | career-ops integration โ career-ops added Good Jobs as a providers/goodjobs.mjs source; ongoing collaboration on integration depth (/recent-jobs, /search-semantic) and a self-hosting guide in career-ops-hq/career-ops#3521 |
| 2026-08-22 | Global search โ opt-in coverage for the US, UK, and Singapore (LinkedIn, Indeed, RemoteOK, We Work Remotely, Glassdoor, USAJOBS, Dice) alongside the Vietnam market |
| 2026-04-11 | CV / skill matching โ paste a CV or skill list and AI intent detection maps it to a canonical job keyword, with results scored against it |
| 2026-03-25 | Summary description โ background LLM summarization of long job descriptions, surfaced inline in the UI |
21 sources, one query. Every board below is scraped live on each search and merged into a single deduplicated feed.
| Board | Best known for | Scraping |
|---|---|---|
| International companies & senior roles | Headless Chromium, full description enrichment | |
| ITViec | IT jobs, transparent salary ranges | Static HTML, full enrichment |
| TopCV | Largest VN general job board | Static HTML, full enrichment |
| VietnamWorks | Established enterprises, HR-first | Static HTML, full enrichment |
| TopDev | Developer-focused roles | Static HTML, full enrichment |
| JobsGo | Startups & SMEs | Static HTML, full enrichment |
| CareerLink | Japanese-affiliated companies | Static HTML, full enrichment |
| CareerViet | Broad coverage across industries | Static HTML, full enrichment |
| Glints | Southeast Asia startups | Headless Chromium, full enrichment |
| ViecOi | Foreign-invested firms in VN | Static HTML, full enrichment |
| Indeed VN | Aggregated listings at scale | Static HTML, inline enrichment |
| TechJobs | IT job aggregator, company career pages | Public website, server-rendered data |
| Xรณm Jobs | Data & AI roles | Public website, static HTML |
| Google Careers | Google's own openings in Vietnam | Headless Chromium |
Type any supported city โ new york, london, singapore โ and the right boards are chosen automatically.
| Board | Best known for | Scraping |
|---|---|---|
| All three markets, one scraper | Headless Chromium | |
| Indeed | Per-country domains, huge volume | Static HTML |
| RemoteOK | Fully remote dev jobs | Public JSON API |
| We Work Remotely | Remote-first companies | Public RSS feed |
| Glassdoor | Salary data + company reviews | Headless Chromium, list-page only |
| USAJOBS | US federal government jobs | Official API |
| Dice | US tech contracting & full-time | Static HTML |
Every posting keeps its original link โ Good Jobs never republishes, it points you home.
| โก Real-time streaming | Results arrive job-by-job via SSE as each scraper finishes โ no waiting for the slowest board |
| ๐ค AI intent detection | Paste a CV, a skill list, or a vague phrase โ an LLM maps it to a canonical job keyword (with Vietnamese โ English translation) |
| ๐ง Vector supplement | Related jobs from other cached keywords are retrieved via embeddings and appended on cache misses |
| ๐ท๏ธ Skill extraction | Tech skills auto-tagged per job from title + description, rendered as pills in the UI |
| ๐ Self-warming cache | ~30 keywordรlocation pairs re-scraped every 2 hours; new jobs merged by link dedup; jobs pruned after 14 days |
| ๐ Free-text locations | No dropdowns. "hcmc" โ Ho Chi Minh City, typos corrected, country inferred from the city |
| ๐ฆ Fair concurrency | A semaphore caps concurrent scrapes; user requests jump ahead of background warmups |
| ๐งฎ All Jobs filters | Homepage feed merges the Redis cache with the D1 archive; filter by category, location, or source, with a jobs-per-page selector |
| ๐ฐ News desk | /news โ AI-generated Vietnamese labor-market articles, auto-published twice a day and cross-posted to LinkedIn |
docker compose up| Service | URL |
|---|---|
| Frontend | http://localhost |
| Backend API | http://localhost:8000 |
| API docs (Swagger) | http://localhost:8000/docs |
That's it โ type a job title (or paste your CV) and a city, and watch results stream in.
| Endpoint | Method | Description |
|---|---|---|
/scrape-stream |
POST | Main SSE endpoint โ streams cached, data, vector-results, and enrichment events |
/scrape |
POST | Blocking scrape (returns full job list) |
/classify-input |
POST | LLM intent detection: free text โ canonical keyword |
/normalize-city |
POST | Typo correction / abbreviation expansion for cities |
/suggest-query |
POST | Query suggestions |
/search-semantic |
GET | Vector search across cached jobs |
/recent-jobs, /stats |
GET | VN-facing views over the cache |
/cache/status, /cache/overview |
GET | Cache keys with fetched_ago and job_count |
/cache/scrape |
GET | Trigger a scrape for a specific key |
/warmup/keywords |
GET / POST | Inspect / extend warmup keyword pairs |
/health |
GET | Health probe |
User request
โ
โผ
Cache hit? โโyesโโโถ Stream cached jobs instantly (event: cached)
โ โ
no โผ
โ Vector supplement from related
โผ cached keywords (event: vector-results)
Semaphore
queue
โ
โผ
Phase 1 โโ All scrapers for the resolved country run concurrently
โ Results streamed as each finishes (event: data)
โ
โผ
Phase 2 โโ Per-site description enrichment โ VN sources (LinkedIn, TopCV,
ITViec, TopDev, JobsGo, CareerLink, Glints, ViecOi,
VietnamWorks, CareerViet) or global sources (LinkedIn only;
RemoteOK/We Work Remotely return full descriptions in Phase 1,
Glassdoor is list-page-only, Indeed enriches inline in Phase 1)
โ streamed job-by-job in background
- Results are cached permanently in Redis by
(keyword, location); individual jobs are pruned after 14 days (RECENT_DAYS). Global entries are namespaced (jobs:{country}:โฆ) and excluded from VN-facing views and warmup. - ๐ Direct submissions: Headhunters can submit a job via
POST /submissions; after admin review (/admin/submissions/*, gated byADMIN_SECRET) it's merged into search results as source"Direct". Stored in Redis undersubmissions:{pending,approved,rejected}, never written into the keyword/location cache. - Background warmup: ~30 VN keywordรlocation pairs every 2 hours, checked every 10 minutes. LinkedIn uses
f_TPR=r7200for incremental 2-hour windows; other scrapers refetch the full window. New jobs merge into existing caches, deduplicated by link.
goodjobs/
โโโ backend/
โ โโโ main.py # FastAPI app, routes, semaphore queue, warmup scheduler
โ โโโ src/
โ โโโ constants.py # HEADERS, CHROMIUM_ARGS, RECENT_DAYS, skill patterns
โ โโโ models.py # Pydantic models (Job, ScrapeRequest)
โ โโโ matching.py # Title matching, skill extraction, level tagging
โ โโโ cache.py # Redis helpers (VN/global namespacing, merge, prune)
โ โโโ vector.py # Embeddings, vector index, supplement search
โ โโโ intent.py # LLM intent detection, city normalization
โ โโโ warmup.py # Warmup scheduler, per-site enrich pipeline
โ โโโ summarizer.py # On-demand description summariser
โ โโโ ratelimit.py # Per-IP rate limiting middleware
โ โโโ submissions.py # Headhunter job-submission store (pending/approved/rejected)
โ โโโ graphql_schema.py # GraphQL schema (jobs query)
โ โโโ scrapers/ # One module per job board (see tables above)
โโโ frontend/
โ โโโ index.html # UI layout and styles
โ โโโ privacy/, terms/, contact/, admin/, post-job/
โ โโโ src/
โ โโโ main.ts # SSE client, fetch orchestration
โ โโโ api.ts # Stream parser, AI classify/normalize calls
โ โโโ ui.ts # Table rendering, modal, skill pills, badges
โ โโโ types.ts # Shared TypeScript interfaces
โโโ thirdparty/
โ โโโ career-ops/ # Git submodule: career-ops (consumes this API via providers/goodjobs.mjs)
โโโ docker-compose.yml # Local development
โโโ docker-compose.server.yml # Production (+ cloudflared tunnel)
โโโ .claude/skills/ # Agent skills for common repo tasks
Common tasks (also available to coding agents as skills):
- Add a scraper: create
backend/src/scrapers/<site>.py, export frombackend/src/scrapers/__init__.py, register inbackend/main.pyโ seeadd-scraper - Add a skill keyword: update
_SKILL_PATTERNSinbackend/src/constants.py - Add a warmup keyword:
POST /warmup/keywordsor edit_WARMUP_KEYWORDSinbackend/src/warmup.py - Check cache state:
GET /cache/status
Pushing to main triggers GitHub Actions:
- Backend โ Docker image built โ pushed to Docker Hub โ deployed over SSH (
backend.yml) - Frontend โ Built and published to GitHub Pages (
frontend.yml)
Required repository secrets:
| Secret | Purpose |
|---|---|
DOCKERHUB_USERNAME / DOCKERHUB_TOKEN |
Docker Hub login |
SERVER_HOST / SERVER_USER / SERVER_SSH_KEY / SERVER_PASSWORD / SERVER_PORT |
SSH deploy target |
VITE_API_URL |
Backend API URL baked into the frontend build |
CLOUDFLARE_TUNNEL_TOKEN |
Cloudflare tunnel auth token |
A separately-operated instance runs outside this CI/CD flow, with its own cron watchdog (restarts on DNS breakage, a crashed container, a wedged event loop, or a stalled scrape scheduler via GET /warmup/heartbeat). That script is versioned at ops/watchdog.sh for review; deploying a change to it is a manual copy to that host, not part of this repo's automation.
This repo ships agent skills so coding agents (Claude Code, opencode, โฆ) can work on it effectively:
add-scraperโ end-to-end recipe for adding a new job boarddebug-scrapersโ diagnosing broken selectors, anti-bot blocks, and empty resultscache-opsโ inspecting, flushing, and reasoning about the Redis cacherun-and-verifyโ start the stack and verify changes end-to-end
career-ops is vendored as a git submodule at thirdparty/career-ops (branch feat/goodjobs-provider). It consumes Good Jobs as a source via providers/goodjobs.mjs, a thin client that calls the public POST /scrape endpoint and normalizes the results.
# Clone with the submodule
git clone --recurse-submodules https://github.com/vnk8071/goodjobs.git
# Or, in an existing clone
git submodule update --init --recursiveTest the provider:
cd thirdparty/career-ops
node --test tests/providers/goodjobs.test.mjsThe unit tests cover URL resolution, request building, normalization, and retry behavior. They do not hit the network. The provider's default backend is https://api.goodjobs.io.vn. Because career-ops' SSRF guard blocks loopback addresses, a local docker compose up instance cannot be used as a source; point api: at a publicly reachable HTTPS deployment instead.
To update the submodule to the latest branch commit:
git submodule update --remote thirdparty/career-opsmcp/goodjobs_mcp.py exposes Good Jobs to MCP clients (Claude Code, Claude Desktop, โฆ) as read-only tools over stdio. It calls the public backend by default, so no local stack is needed.
| Tool | Wraps | Purpose |
|---|---|---|
search_jobs |
POST /scrape |
Live search by keyword and location; newest first |
recent_jobs |
GET /recent-jobs |
Latest postings across cached searches, optionally one board |
semantic_search |
GET /search-semantic |
Match by meaning, e.g. a pasted CV summary |
classify_keyword |
POST /classify-input |
Turn free text or a CV into a canonical job title |
normalize_city |
POST /normalize-city |
Fix city typos and abbreviations ("hcmc" โ Ho Chi Minh City) |
cache_status |
GET /cache/status |
Cache freshness and job counts per keyword and location |
Admin and submission routes are deliberately not exposed.
cd mcp
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
python -m pytest -q test_goodjobs_mcp.py # unit tests, no networkRegister it with Claude Code:
claude mcp add goodjobs -- /absolute/path/to/goodjobs/mcp/.venv/bin/python /absolute/path/to/goodjobs/mcp/goodjobs_mcp.pySet GOODJOBS_API_URL to point at another deployment. Use http://localhost:8000 for a local docker compose up. The first search_jobs call on an uncached keyword can take a minute, because it runs a full multi-board scrape.
PRs are welcome! The most valuable contribution is a new job board for your country โ see CONTRIBUTING.md and the add-scraper guide.
MIT โ each job posting links back to its original source. See also our privacy and terms pages.