Skip to content

Getting Started

Prerequisites

  • Python 3.14+
  • uv (package manager)
  • Adzuna API key (free, for job search)
  • Docker & Docker Compose or Supabase account (for PostgreSQL)
  • At least one LLM API key (for future JD analysis): Claude (console.anthropic.com), OpenAI, or Gemini

Installation

git clone https://github.com/Misoto22/kairos.git
cd kairos
uv sync                              # Install all dependencies

First-Time Setup

uv run kairos init

This interactive wizard walks through 6 steps:

  1. Profile — Name, country (AU/US/UK/CA/NZ), city (from predefined list), target roles
  2. Database — Choose Docker PostgreSQL (local) or Supabase (cloud, no Docker needed)
  3. Adzuna API — Free API key from developer.adzuna.com
  4. LLM Model — Pick from list (Claude, GPT, Gemini, DeepSeek) or enter custom model string
  5. API Server — Bind host and port (default 0.0.0.0:8880)
  6. Search Defaults — Platforms, posted-within days

Start Database

docker compose up -d postgres        # Start PostgreSQL 18
uv run alembic upgrade head          # Create tables

# Connection string set during `kairos init`
uv run alembic upgrade head          # Create tables in Supabase

Search Jobs

# Start the API server (in one terminal)
uv run kairos-server                  # http://localhost:8880
# Or: ./start.sh                      # postgres + migrations + server in one go

# Search (in another terminal)
uv run kairos jobs search "software engineer" -c AU -l Sydney
uv run kairos jobs search "developer" -i     # interactive country/city picker
uv run kairos jobs list                       # view saved jobs
uv run kairos jobs view <job-id>              # job details

(Optional) Run the Web Frontend

cd frontend
npm install                                   # first-time deps
npm run dev                                   # http://localhost:5173

Or via Docker (full stack: postgres + backend + frontend):

docker compose up -d                          # frontend at http://localhost:5180

See Web App reference for what the UI exposes.

Configuration

Config file: ~/.config/kairos/config.toml

Manage via CLI:

uv run kairos config view                         # show current config
uv run kairos config set adzuna.app_id "your-id"   # set a value
uv run kairos config path                          # show file location

Or edit directly:

[profile]
name = "Your Name"
location = "Sydney"
country = "AU"
target_roles = ["Software Engineer", "Backend Developer"]

[database]
provider = "local"                              # "local" or "supabase"
url = "postgresql+asyncpg://kairos:kairos@localhost:5432/kairos"

[llm]
model = "claude-sonnet-4-20250514"

[adzuna]
app_id = ""                                     # from developer.adzuna.com
app_key = ""

[search]
platforms = ["adzuna"]                          # adzuna, seek, linkedin
job_type = ""                                   # fulltime, parttime, contract
salary_min = 0
posted_within_days = 14

[api]
host = "0.0.0.0"
port = 8880

Priority: environment variables > .env file > config.toml > defaults

Tip: LLM API keys are set via environment variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY. Only the key for your configured model is required.