What the review turns on
A security review of an HR agent comes down to four questions. Which employee data can the agent reach? What can it do with that data? Who allowed it? And what can the company produce six months from now, if a works council, a regulator or one employee asks?
The documents that usually answer them are a questionnaire and a data processing agreement. Both describe what a vendor intends to do. Neither lets the reviewer read the line that decides whether the agent can open payroll.
A manifest in the project repository answers all four, because it is the file the runtime reads before a session starts. A reviewer can open it and read the diff of the last change to it.
The manifest holds the grants and nothing else
kortix.yaml sits at the root of the project repository and declares each agent and what it may reach. It holds no prompt text. Behaviour lives in the agent's own .md file, a stock OpenCode agent file, so the manifest stays short enough to read out loud in a review meeting.
Kortix's starter manifest opens with this comment:
# One map per project, GOVERNANCE ONLY — connectors/secrets/kortix_permissions/# skills grants the runtime itself can't express, plus workspace (the git# boundary) and enabled. `file` names the agent's `.md`; everything else# (description, mode, permission, temperature, the prompt itself, …) lives# in that file — open it to see/change what the agent actually does.# v2 is deny-by-default: an omitted connectors/secrets/kortix_permissions/# skills grant resolves to "none", so a scoped specialist starts locked down.# The starter's own `kortix` agent is deliberately# granted "all" across the board so a fresh project is capable out of the# box — narrow it once you know what this project actually needs.That last paragraph is the honest part of the file, and it is the one an HR team acts on. A new project's default agent can do a lot, because a project that could do nothing would be a poor first hour. The first commit that matters is the one that takes the all off the agent that reads employee records.
An omission does the work here. An agent declared with no connectors block calls no connector at all. Reach arrives one named line at a time, so the reviewer counts the lines instead of trusting a paragraph about least privilege.
The same block names the secrets an agent may use. Those values are set in the secrets manager before a session starts, which means a name that appears in the manifest without a grant to that agent is a name the agent cannot use.
The rule that holds a call, and who sets it
Approval gates you set. Off until you set them.
policy.default_mode decides the calls that no rule matches, and it arrives set to allow_all. Switch it to risk and a write or a destructive call needs approval while a read still runs. That switch is the difference between a policy someone meant to write and one the reviewer can point at.
Rules get more specific than a mode. A rule matches one tool path, and a condition can narrow it to the value of a single argument. An HR agent that emails a hiring manager inside the company can run unattended. The same send tool, called with an address outside the company, holds. Each rule carries one of three actions, so the team decides between running the call, holding it for a person, or refusing it.
Refusal suits the connectors an agent should never touch. A policy agent that answers handbook questions has no business calling payroll, and one block rule turns that separation into a line in the file.
A held call stops at the exact argument that matched the rule. Approval holds the call; the agent's turn pauses and resumes, and the HR lead who answers decides whether the write goes ahead.
Read the docs for the rule shape.
Who signs in, and who may act
SAML 2.0 single sign-on and SCIM 2.0.
SCIM 2.0 keeps the people who can sign in in step with the identity provider, so a departure in that system is a departure from the project too. SAML means the sign-in the reviewer audits is the one the company already runs, with the group membership it already trusts.
Per-resource permissions for people and agents. Roles, groups, and an audit trail.
The second question in most reviews is narrower than the first. Which people inside HR can open the sessions where an employee's record appears? Roles and groups answer that per resource, and the audit trail records the changes. An agent is one subject of those permissions; the people who can see what it did are the others, and both are visible to whoever signs off.
Where it runs, and where the record stays
Run it on Kortix Cloud, in your VPC, or on your own on-prem network. Self-host is free.
Where it runs settles most of the residency conversation early. A company that keeps employee records in its own datacentre can keep the agent there too, and a company without that rule can start on the managed option and move later, since the agents and the manifest travel with it.
Self-host is not a sealed network, and a reviewer should ask about the topology instead of assuming a wall. The instance pulls its images from the internet and the default sandbox provider is remote, so the boundary you get is the one you design around those two facts.
The record has two halves. Each session keeps its own history of what it read and wrote, and the work it produced lands as commits on the session's branch in the project repository. The diff of a change survives the session that made it, so a reviewer can start from the repository and read forward.
Two checklists next to a file
Moveworks publishes a long guide to writing an employee data privacy policy for AI. The recommendation list is a good one: role-based access, encryption, audit trails, subject-access workflows, vendor controls across the HR systems (moveworks.com). It is written by a vendor that sells an HR assistant, and the advice holds up regardless.
AIHR covers the other half of the problem: purpose limitation, inferred data, fairness testing, human review of high-impact decisions, and the framework that holds them (aihr.com). An HR lead reading both comes away knowing what to require.
Neither piece tells a reviewer where a requirement is met. A checklist names role-based access; a manifest shows the grant. A checklist says a person reviews the high-impact decisions; a policy rule names the call that waits, and the argument that makes it wait. What the reviewer gets from the file is a promise they can open, diff, and hand to the next auditor.
What the company still owns
The policy text, the escalation bar, the rubric behind a screening score and the approval rules are company decisions, and no vendor supplies them. Kortix supplies the mechanism around them: a manifest that grants, rules that hold or refuse a call, roles and groups that decide who sees what, and a repository that keeps the history.
The policy desk page shows the same model on an HR inbox, where the agent drafts and a person sends. The five workflows on the home page run on the same manifest, the same identity provider and the same approval rules.