Candydati

AI agent asked to install, deploy or host Candydati? Follow skills/candydati-deploy/SKILL.md: it needs only access to the user's Dokploy (or a fresh server) and asks the user nothing else.

Why

An ATS is not the enemy. Candidates often picture the applicant tracking system as a black box that hides their CV or filters them out before a person reads it. Software does what the people running it decide: the same tool can leave applicants in silence or answer every one of them. The difference lies in how it is set up and used.

That is why the source of Candydati is public. The rules it applies are code anyone can read, check and improve, and the good practices are built into the product instead of being left to goodwill. Most hiring tools hide the salary, the process and the outcome from the people who apply; here transparency is structural, not optional: a deployment cannot switch these principles off.

• Salary range in clear. A job ad without a range cannot be published.
• Declared selection process. The stages, who runs them and how long each one takes are visible before applying.
• No application without an outcome. Every candidate gets an answer; a job with open applications cannot be closed.
• No automated decisions. The assistant works on the process. It never ranks, scores or rejects people. The only score in the product rates the job ad, not who applies; the CV reader extracts facts (roles, skills, languages) shown next to the original, without judging them.
• Agentic-ready. Everything in the UI is available through a REST API (OpenAPI) and an MCP server, with the same permissions.
• Privacy by design. Versioned consent, retention and automatic erasure, data subject rights, full export in open formats. AI included: the assistant and external agents over MCP (Claude Code, Codex, Cursor...) see candidates by first name and id only. Surnames, emails, phone numbers, links, addresses and other identifiers are removed before any text reaches a model, in CVs and messages too (ADR 0010).

Status: pre-1.0 (see the changelog). Full product definition: docs/PRODUCT.md.

Features

Hiring

• Structured job ads with a deterministic publish standard (salary, process, contract, work mode) and Italian compliance checks
• Careers page with structured data (JobPosting), XML feed and a public read-only ads API
• Careers page builder: hero with image or video, gallery, values, numbers, testimonials and more, with live preview, drafts and publication; privacy-first video embeds
• Applications without registration, with versioned consent
• Pipeline whose stages are the ones declared in the ad; candidate database search; original CV next to extracted data
• Find candidates for a job on objective criteria a person confirms (skills, languages, minimum experience, location): a filter over the job's applicants and the talent pool, with no score and no ranking; CVs that could not be checked are reported, not dropped

Collaboration

• Organizations, roles and per-job selection teams
• Interview feedback without login, via personal links
• Hiring needs intake, optional budget and salary approval, stalled job flags
• Reports: time to hire, conversion per stage, sources, response times

Communication and automation

• Email templates, single and bulk sends, inbound email attached to the candidate
• Response deadlines and reminders; triggers per stage (none decides about a candidate)

Agents and integrations

• REST API with OpenAPI, API keys, MCP server, process assistant (models via Mastra, off by default)
• Pseudonymized data for every model: first name and id only, identifiers replaced by markers such as [surname]; message drafts keep {{candidate.lastName}} as a variable that the person's composer fills in
• MCP prompts for HR workflows (write a job ad, answer the inbox, find candidates on declared criteria, weekly report, interview kit), with no install
• Signed webhooks fed by a transactional outbox

Privacy and data

• Retention, automatic erasure, data subject rights, append-only audit log
• Minimization: no special-category fields, CV extraction drops photo and birth date, models never receive surnames or contacts
• Criteria searches only reach people whose consent covers the job, refuse protected characteristics and are audited
• Import from CVs and spreadsheets with preview and undo; complete export
• Migration from another ATS through an open package format, with preview, an explicit responsibility step and undo; an agent skill builds the package (guide)

Migrate from another ATS

Bring jobs, stages, candidates, applications with their outcomes and dates, notes, past emails, CVs and attachments from your previous ATS. Everything goes through one open package format: you see a preview, confirm that your organization is responsible for the transfer, and can undo it. Scores and ratings are never imported.

Source	How it connects	Status
Teamtailor	API key
Greenhouse	Harvest v3 API credentials
Workable	API token
Recruitee	personal API token
Zucchetti InRecruiting	export file (spreadsheet + ZIP of CVs)
Any other ATS or a spreadsheet	package built by an AI agent with the migration skill	available

Beta means built on the vendor's public documentation and not yet verified on a real account: check the preview before confirming, and tell us how it went. What each connector brings and what it cannot: migration sources. Step by step: the migration guide. Product names are trademarks of their owners; Candydati is not affiliated with them.

Screenshots

Pipeline: candidates across the declared stages of a job	Job ad editor: salary and process required, live preview
Careers page: sections built in the page builder with a live preview	Candidate: stage, notes and interview feedback, no scores

Demo data is invented. Regenerate with pnpm --filter @candydati/e2e screenshots against a running dev stack.

Quick start (development)

Requirements: Node 24, pnpm 10 (corepack enable), Docker with Compose v2.

cp .env.example .env
pnpm install
pnpm infra:up       # Postgres :5434, MinIO :9000
pnpm db:migrate
pnpm dev            # web http://localhost:3000, api http://localhost:4100

Locally, emails go to Mailpit (http://localhost:8025). Checks: pnpm lint, pnpm typecheck, pnpm test (tests need pnpm infra:up). Every environment variable is listed in docs/ENVIRONMENT.md.

Self-hosting

With a coding agent (the shortest way). On a server with Dokploy, create an API key (Dokploy, Settings, Profile, API/CLI) and ask your agent (Claude Code, Codex, Cursor):

Deploy Candydati on my Dokploy at <Dokploy URL>, following https://github.com/fabrilallo/candydati/blob/main/skills/candydati-deploy/SKILL.md

It creates the service from the published template, deploys it and gives you the link to create the first account; you then set up email in the app (Settings, Email). Nothing else to prepare: Dokploy generates the secrets and the domain.

On a server without Dokploy. You need a Linux server with 2 vCPU and 4 GB RAM (for example Hetzner Cloud CX23 or the Arm CAX11, or OVHcloud VPS-1: about €5–7 a month in October 2026), a domain pointing to it and an email account to send from (Resend or any SMTP, including your company mailbox). No other accounts. On the server:

curl -fsSL https://github.com/fabrilallo/candydati/releases/latest/download/install.sh | sudo bash

The installer asks a few questions, installs Docker if missing, generates every secret and starts the whole stack (Postgres 17, MinIO, api, worker, web) with automatic HTTPS (Caddy) and daily backups. It ends with the link that creates the first owner. Day to day: candydati status, candydati update, candydati backup, candydati help. Step by step: the documentation site.

From the sources instead (cp .env.example .env, then docker compose -f docker-compose.prod.yml up -d --build), with SIGNUP_MODE=invite_only the first owner signs up with the setup link the api prints in its logs at first start. Guides:

• Operations: backups, upgrades, monitoring
• Deploy with Docker Compose, with network, volumes and several instances on one host
• Deploy with Dokploy, by hand or hands-off with a coding agent through the deploy skill
• Environment variables and reverse proxy log masking

Architecture

Business logic lives only in packages/core. REST routes, assistant tools and MCP tools are thin adapters over the same use cases, with the same permissions and the same audit trail.

flowchart LR
  subgraph clients[Clients]
    rec[Recruiters]
    cand[Candidates]
    agents[External agents]
  end
  web["web<br/>Nuxt SSR + proxy"]
  subgraph api[api · Fastify]
    rest[REST + OpenAPI]
    auth[Better Auth]
    mcp[MCP server]
    asst[Assistant]
  end
  core["core use cases<br/>permissions · audit<br/>transactions · org scoping"]
  subgraph pg[Postgres 17]
    data[(Data)]
    audit[(audit_log)]
    outbox[(outbox_event)]
    boss[(pg-boss queues)]
  end
  worker["worker<br/>CV extraction · emails · automations<br/>webhooks · retention · imports · exports"]
  s3[(S3 storage)]
  mail[Email provider]
  llm["LLM provider<br/>via Mastra"]
  hooks[Webhook consumers]

  rec & cand --> web
  agents -->|API key| web
  web -->|"/api/** and /mcp"| api
  rest & auth & mcp & asst --> core
  core --> data & audit & outbox & boss
  core --> s3
  asst --> llm
  boss --> worker
  outbox --> worker
  worker --> data
  worker --> s3
  worker --> mail
  worker --> llm
  worker -->|signed| hooks

Life of an application:

sequenceDiagram
  autonumber
  actor C as Candidate
  participant W as web
  participant A as api
  participant K as core
  participant P as Postgres
  participant Q as worker
  actor R as Recruiter
  participant X as Webhook consumer
  C->>W: Apply (form, CV, consent)
  W->>A: POST public application
  A->>K: intake use case
  K->>P: One transaction: candidate, application, consent, audit_log, outbox_event
  A-->>C: Confirmation
  K-)P: After commit: queue cv.extract
  P-)Q: pg-boss delivers the job
  Q->>P: Store extracted data next to the original CV
  R->>A: Move to next stage
  A->>K: Permission check, update, audit_log, outbox_event
  K->>P: Same transaction, then queue email
  P-)Q: Outbox publisher and email.send
  Q-)C: Stage email
  Q-)X: Signed webhook

More in docs/ARCHITECTURE.md and the decision records.

Documentation

• Product: principles, scope, job ad standard, agent and GDPR approach
• Architecture and decision records
• Design system
• Environment variables, Operations, Migrations
• Public data schemas, legal templates (Italian, need legal review)

Roadmap

No dates. Deferred from the current scope (PRODUCT.md §3.3):

• Scorecards and interview kits
• Restricted stages: feedback and notes visible only to owners, admins and the hiring manager
• Interview scheduling through an integration with a scheduling service
• Migration connectors out of beta once a real migration confirms each one; more sources on request

Contributing

Contributions are welcome. Read CONTRIBUTING.md and the Code of Conduct. Tests are written first and live next to the code.

Security

Report vulnerabilities privately as described in SECURITY.md. Do not open public issues for them.

Author

Created and maintained by Fabrizio Lallo ([email protected]), founder of TechCompenso and XCompenso, and creator of FuffAnnuncio and Riccometro. The job ad quality analysis in this project is derived from FuffAnnuncio.

License

Business Source License 1.1 (BUSL-1.1), by Fabrizio Lallo.

• Free: read, modify and self-host it, including in production to run your own organization's hiring. Consultants may install and run it for a single organization's own hiring.
• Requires a commercial license: offering it to third parties as a hosted service (an ATS or recruiting SaaS) or embedding it in a product you sell. Write to [email protected].
• Becomes open source: each version converts to GNU AGPL v3 (AGPL-3.0-only) four years after its first public release.

The license text is binding; this summary is not.

---

Italiano. ATS agentico, aperto e installabile sul tuo server, pensato per chi si candida: RAL in chiaro obbligatoria, processo dichiarato, nessuna candidatura senza esito. Questo README in italiano: README.it.md.