Huly Integration Guide for Recruitment

Self-hosted ATS setup, Account API, wire-level discoveries, seed paths, and recruitment configuration

1. Self-Hosted Stack

Huly self-hosted runs as a 14-container Docker Compose stack on Ubuntu 24.04. We used the --quick flag for local testing on macOS (OrbStack).

Services

Quick Start

git clone https://github.com/hcengineering/huly-selfhost.git
cd huly-selfhost
./setup.sh --quick
# → Generates config, secrets, starts all 14 containers
# → Huly available at http://localhost:8087 in ~60 seconds

Minimum Resources

2. Account API (Reverse-Engineered)

Huly's Account service exposes a JSON-RPC over HTTP API at /_accounts. This is not publicly documented. We discovered these methods by inspecting the bundled JavaScript in the account container.

Endpoint

POST http://localhost:8087/_accounts
Content-Type: application/json
Authorization: Bearer {token}  (for authenticated methods)

Discovered Methods

signUp — Create a new account

{
  "method": "signUp",
  "params": {
    "email": "admin@agilex.co.za",
    "password": "AgileX2024!",
    "firstName": "Craig",
    "lastName": "Sobey"
  }
}
→ { "result": { "account": "uuid", "token": "jwt", "name": "Craig Sobey" } }

createWorkspace — Create a workspace

{
  "method": "createWorkspace",
  "params": {
    "workspaceName": "AgileX Recruitment",
    "workspaceUrl": "agilex-recruitment"
  }
}
→ { "result": { "token": "workspace-jwt", "workspace": "uuid", "role": "OWNER" } }

Gotcha: Requires workspaceName AND workspaceUrl as separate fields. Using just name returns BadRequest.

createInviteLink — Generate invite for a user

{
  "method": "createInviteLink",
  "params": {
    "email": "thandi@agilex.co.za",
    "role": "OWNER",      // OWNER | MAINTAINER | USER | GUEST
    "expHours": 720
  }
}
→ { "result": "http://localhost:8087/login/join?inviteId=123456" }

Gotcha: The autoJoin parameter exists but requires a "schedule" service permission in the token. Use the two-step flow instead (createInviteLink + join).

join — Accept an invite and join workspace

{
  "method": "join",
  "params": {
    "email": "thandi@agilex.co.za",
    "password": "AgileX2024!",
    "inviteId": "123456"
  }
}
→ { "result": { "token": "workspace-jwt", "workspace": "uuid" } }

getWorkspaceMembers — List workspace members

{
  "method": "getWorkspaceMembers",
  "params": {}
}
→ { "result": [{ "person": "uuid", "role": "OWNER" }, ...] }

Other Methods Found (not all tested)

Roles

3. Wire-Level Discoveries

We wrote probe scripts (scripts/discover.ts and scripts/probe.ts) that connect to a live Huly workspace via @hcengineering/api-client and query the data model. These findings are not documented anywhere in Huly's public docs.

Key Findings (verified 2026-04-26)

4. Recruit Data Model

Person (contact:class:Person)
  name: "LastName,FirstName"
  city: string
  ├── recruit:mixin:Candidate  { title?, source? }
  ├── Channel[] (Email, Phone, LinkedIn, Homepage)
  └── Application[] (one per Vacancy applied to)

Vacancy (recruit:class:Vacancy extends task:class:Project)
  name: string (job title)
  description: string (markdown)
  type: recruit:template:DefaultVacancy
  statuses: Status[] (7 default pipeline stages)
  members: [], owners: [], private: false, archived: false
  ├── Applicant[] (one per Talent in this pipeline)

Applicant (recruit:class:Applicant)
  space: Vacancy (Vacancy IS a Space)
  attachedTo: Person (Talent)
  collection: 'applications'
  status: recruit:taskTypeStatus:* (pipeline stage ref)
  assignee?: Employee ref
  identifier: string (auto-generated)

Pipeline Stages (Default)

Channel Providers

5. Two Seed Paths

We implemented two different approaches to populating a Huly recruitment workspace:

6. Recruitment Configuration

Workspace: AgileX Recruitment

Staff (11 members)

All staff emails: firstname.lastname@agilex.co.za / Password: AgileX2024!

HR Departments

MCP Demo Data (V3 Seed)

Vacancy: V3 · ML Platform Engineer (LLM/MLOps) — R1.4M–R1.8M CTC, Cape Town hybrid.

7. MCP Server Integration

See the full MCP specification: Huly Recruit MCP Spec

Quick Reference

8. Path B — Google Workspace as Document Store

Huly stores metadata and links only. All durable artifacts live in Google Workspace.

Google Drive Folder Structure

AgileX Recruitment/
├── Candidates/
│   ├── Active/
│   │   └── {FirstName LastName}/
│   │       ├── CV.pdf
│   │       ├── References/
│   │       └── Notes.gdoc
│   ├── Placed/
│   └── Archive/
├── Clients/
│   └── {Client Name}/
│       ├── Contract.pdf
│       └── Vacancy_Briefs/
├── Templates/
└── Reports/

9. Gotchas & Lessons Learned

AgileX Huly Integration Guide · May 2026 · agilex.co.za · 2nth.ai