Skip to content

Onboarding: from a clean machine to scored jobs

This guide takes you from nothing installed to a job list that fills itself, is scored against your resume and what you value, and drops postings once they close. Everything runs in Docker. You only need the kairos CLI inside the backend container.

Budget about 15 minutes, most of it the first image build and the first harvest.

1. Prerequisites

  • Docker with Compose v2 (docker compose version)
  • Git
  • A resume in Markdown with ## section headings (Summary, Work Experience, Projects, Technologies, Education, ...). examples/resume.example.md shows the shape.
  • For fit scores, one of:
    • a Claude subscription: run claude setup-token on a machine where you are signed in to Claude Code, and keep the token it prints. It must stay on one line: a token pasted with a line break fails with Not logged in (401);
    • an LLM API key (Anthropic, OpenAI, Gemini, ...) for LiteLLM.

Nothing else is required. Adzuna, the official job API, is optional (step 6).

2. Get the code and start the stack

git clone https://github.com/Misoto22/kairos.git
cd kairos
cp .env.example .env

Open .env and fill in the scorer credential you chose:

CLAUDE_CODE_OAUTH_TOKEN=...      # Claude subscription (from `claude setup-token`)
# or
ANTHROPIC_API_KEY=...            # or OPENAI_API_KEY / GEMINI_API_KEY

.env is git-ignored. Never commit it. If you keep secrets in a manager, inject them when you start the stack instead (for example op run --env-file=.env.op -- docker compose up -d).

docker compose up -d --build --wait

This starts PostgreSQL, the API on http://127.0.0.1:8880 and the web app on http://127.0.0.1:5180. Each binds to localhost only, because the API has no authentication. If a port is taken, change KAIROS_API_PORT, KAIROS_WEB_PORT or KAIROS_PG_PORT in .env.

Check that the CLI answers:

docker compose exec backend kairos --help

Shorter commands

alias kairos='docker compose exec backend kairos' lets you type kairos ... from the repository folder. The examples below use the full form.

3. Give Kairos your resume

The backend container reads files from ./input, mounted read-only at /input:

cp ~/Documents/cv.md input/resume.md

4. Run onboarding

There are two ways to do this. The questions and the result are the same.

docker compose exec backend kairos init

For the resume, answer /input/resume.md.

cp examples/onboarding.example.toml input/onboarding.toml
# edit input/onboarding.toml; set resume = "resume.md"
docker compose exec backend kairos init --from /input/onboarding.toml

An answers file makes setup repeatable. Keep it, and run init with it again on a new machine.

Init asks six things:

Step What you decide Where it lands
1. You Name, home region, target roles [profile]
2. Where to look Regions to search; the cities you want in each (none = the whole region) [profile] preferred_cities, [jobs] harvest_regions
3. Resume Path to your Markdown resume Imported as your base resume
4. What matters Your industries; how much each factor counts; where you need visa sponsorship [profile.fit]
5. Fit scoring Claude subscription (model + effort), API key, or none [jobs] fit_*
6. Harvest Search keywords; how often to search [jobs] harvest_*

Then it imports the resume, searches every board once, and scores the first 30 postings. The search takes a few minutes.

What "what matters" means

Every fit score starts from how your resume matches the posting. The factors below then move the score up or down. Each factor takes off, low, medium or high, which caps how far it can move a score: 0, 5, 10 or 20 points.

Factor Counts for a role when…
skills How strictly a stack or seniority gap counts. high: a real gap scores below 50. low: adjacent skills are enough
industry It is in one of industries, written in your own words with what counts in brackets, e.g. healthcare (hospitals, insurers)
career_value The employer's name, scale or bar compounds on a CV; admired_employers names the ones that count most
work_life_balance Hours are sustainable; stated long hours, on-call or weekend work, or a team known for long hours, count against it
foreign_companies The employer is a multinational rather than a local firm; foreign_companies_in limits this to some regions

Two hard rules sit outside the levels. A role in a region listed in needs_sponsorship_in that will not sponsor a visa, or wants citizenship or permanent residency, is capped at 40. One whose posting says it does sponsor gains sponsorship_offered_points (default 20, up to 100): the scorer only says whether the posting offers it, and Kairos adds the points (decision 0015). A posting that says nothing either way, from an employer on the region's official sponsor list, gains listed_sponsor_points (default 10, up to 50). Australia's list is Home Affairs' accredited sponsors as at 15 January 2025; kairos jobs view shows the name it matched, and kairos jobs list --listed-sponsor lists only those employers (decision 0016). Places you picked in step 2 are never marked down for location. When factors pull apart, say a big name with long hours, the reason says so instead of hiding it in the number.

Change any of it later:

docker compose exec backend kairos profile show
docker compose exec backend kairos profile set work_life_balance=high industries=automotive,ERP

The web app's Settings → Fit scoring edits the same values. New weights apply to new scores. To redo the existing ones as well (oldest first, in batches):

docker compose exec backend kairos jobs score --rescore --all

5. See your best matches

docker compose exec backend kairos jobs list --top          # best fit first, with the reason
docker compose exec backend kairos jobs view <id>           # full posting

Or open http://127.0.0.1:5180.

From here Kairos runs on its own for as long as the stack is up:

Every It does Setting
12 h Searches every keyword × region × city × board; saves new postings; keeps a role posted on two boards once [jobs] harvest_hours
after each harvest Scores up to 100 unscored postings, reading each posting's detail page first [jobs] fit_scoring_batch
24 h Asks each posting's site whether it is still open, and archives the closed ones [jobs] availability_check_hours

Run any of them by hand:

docker compose exec backend kairos jobs harvest
docker compose exec backend kairos jobs score -n 50
docker compose exec backend kairos jobs check

6. Watch what scoring costs

Every LLM call is logged with its tokens and its cost at API prices:

docker compose exec backend kairos usage plan max-20x      # pro, max-5x, max-20x or api
docker compose exec backend kairos usage

kairos usage shows calls, input, output and cache tokens, and API-equivalent dollars for the last day, week and month. It then sets those against your plan:

  • Subscription (Pro, Max 5x, Max 20x): what the month's calls would have cost at API prices, as a share of the plan's price. Anthropic publishes no token quota for subscriptions, so this shows value used, not how close you are to a limit.
  • API key: what you spent, and the monthly pace.

Plan prices live in src/kairos/core/plans.toml. Change one, or add your own, under [usage.plans.<code>] in config.toml. Init asks for your plan when you pick the Claude subscription.

7. Optional extras

  • Adzuna (official API, AU/UK/US/...): register free at https://developer.adzuna.com, then set ADZUNA_APP_ID and ADZUNA_APP_KEY in .env and run docker compose up -d. Without them the harvest skips Adzuna and reports it.
  • More cities on one board: in config.toml, harvest_board_cities = { tencent = { CN = ["Shenzhen"] } } searches Tencent in Shenzhen while the other boards keep to your preferred cities.
  • Model and effort: kairos config set jobs.fit_model sonnet for scoring, and kairos config set llm.model opus for JD analysis and tailoring. kairos config set llm.backend litellm moves every call to an API key. On a nine-posting sample, haiku/low ranked postings like sonnet/medium and caught the same dealbreakers, so it is the default.
  • Notes the resume leaves out (where you will relocate, visa status): write them to /root/.config/kairos/watch-profile.md in the container. The scorer appends them to your resume.

Troubleshooting

You see Cause Fix
fit scoring stopped: 3 postings failed in a row The scorer cannot run: no token, a token broken across lines, or a bad model name Check CLAUDE_CODE_OAUTH_TOKEN (one line) or your API key in .env, then docker compose up -d. docker compose exec backend sh -c 'echo hi \| claude -p' should answer
skipped: linkedin AU/Sydney ...: ScrapingError The board refused the request (scraped boards block many server IPs) Nothing to do; the other boards still run. Add Adzuna for Australia (Seek AU and NZ are not bundled)
no candidate profile No base resume imported docker compose exec backend kairos resume import /input/resume.md
has no '## ' section headings The resume is not split by ## headings (init checks this before saving anything) Add ## Work Experience and similar headings
Not saved: ... from kairos config set The value failed validation (unknown key, wrong type, unknown region) Nothing was written; fix the value and run it again
More than one job starts with ... The short id from jobs list matches several jobs Give more characters, or the full id
The API is not running during init Init ran before the API came up docker compose up -d --wait, then the commands init printed

Check a clean install yourself

scripts/e2e-onboarding.sh builds this checkout into a fresh Compose project with empty volumes. It runs kairos init --from examples/onboarding.example.toml, checks that the base resume, the harvested jobs and (with a token) the scores are there, then removes everything:

scripts/e2e-onboarding.sh
CLAUDE_CODE_OAUTH_TOKEN=... scripts/e2e-onboarding.sh     # also scores