Agents & permissions

Define an agent's behavior, skills and harness, give it access to connectors, secrets and Apps, and understand exactly what it is allowed to do.

An agent is a system prompt, a model and tool rules that a session runs, plus grants that decide which connectors, secrets, skills, Apps and Kortix permissions it may use.

What an agent is

An agent has two halves:

• Behavior. The prompt, the model, the mode, and the permission rules for its tools.
• Governance. The grants: connectors, secrets, skills, Apps, Kortix permissions and tools. Governance always lives in kortix.yaml.

Where behavior lives depends on the manifest’s kortix_version:

To add an agent from the dashboard, open Customize → Agents → New. Create in chat starts a session that writes the agent with you. Set up manually opens the project files. You can also commit the files with any git client.

---
description: Answers support tickets from the help desk.
mode: primary
permission:
  bash: ask
---

You answer support tickets. Read the ticket, check the order history,
draft a reply, and submit it for review. Never close a ticket yourself.

kortix_version: 2
default_agent: support
agents:
  support:
    file: agents/support.md
    connectors: [helpdesk]
    secrets: [HELPDESK_API_KEY]
    skills: [kortix-cli, triage]
    kortix_permissions: [project.session.read, project.review.submit]

kortix_version: 3
default_agent: support
agents:
  support:
    description: Answers support tickets from the help desk.
    mode: primary
    prompt_file: prompts/support.md
    permission:
      bash: ask
    connectors: [helpdesk]
    secrets: [HELPDESK_API_KEY]
    skills: [kortix-cli, triage]
    kortix_permissions: [project.session.read, project.review.submit]

Rules for both versions:

• An agent name is 1 to 128 characters: lowercase letters, digits, - and _, starting with a letter or digit.
• The manifest declares at least one agent and sets default_agent.
• In v2, a behavior key (model, mode, prompt, permission, …) in the kortix.yaml block is an error. Put it in the agent file.
• In v2, file names the agent file. Without it, Kortix reads agents/<name>.md. The API does not change file: to move an agent, move the file and update file in the same commit. The full path rules are in the kortix.yaml reference.

An agent change takes effect when it lands on the project’s default branch. New sessions start with it, and running sessions reload it. See How a change takes effect.

The agent file

The agent file holds a v2 agent’s behavior: YAML frontmatter, then a body that is the system prompt. Every field is optional, so a stock OpenCode agent file is valid as is. A v3 block takes the same fields, except disable.

Two names are errors, with a pointer to the replacement:

• tools: use permission, or the tools grant in kortix.yaml (see Tools).
• maxSteps: use steps.

Both harnesses also add the repository’s root AGENTS.md to every agent’s instructions. When the root has no AGENTS.md, they read CLAUDE.md.

Edit behavior in Customize → Agents → the agent → Basics and Model, or from the CLI. behavior.<field> writes the agent file’s frontmatter, and behavior.prompt writes its body:

kortix agents config support --set behavior.mode=primary
kortix agents config support --set behavior.temperature=0.2

Ask, allow or deny

permission decides what the agent does without a person. Each rule resolves to one action:

permission is a bare action for every tool, or an object keyed by tool:

• read, edit, glob, grep, list, bash, task, external_directory, lsp and skill take an action or a map of pattern to action.
• todowrite, question, webfetch, websearch and doom_loop take a bare action only.
• Any other key is a tool name and passes through to the harness.
• A tool with no rule is allowed.

A pattern is matched against the command line for bash, the skill name for skill, the subagent name for task, and the file path for the file tools. * matches any text and ? matches one character. A pattern that ends in * also matches the bare command: git diff * matches git diff.

The most specific rule wins, on OpenCode and on pi, whatever order the keys are written in.

• The longest matching pattern wins, so "*" is the fallback wherever it sits. Two patterns of equal length: the later one in code-unit order wins.
• The same rule picks between keys: bash: ask outranks "*": allow. A tool whose pattern map matches nothing falls back to the "*" key.
• An agent’s own permission outranks the project-wide one in opencode.jsonc.

This agent asks before any shell command, runs read-only git commands freely, and never deletes recursively:

permission:
  edit: allow
  bash:
    "*": ask
    "git status": allow
    "git diff *": allow
    "git log *": allow
    "rm -rf *": deny
  webfetch: ask

• The starter agents use permission: allow. Each session runs in its own sandbox on its own branch.
• bash: deny also denies the terminal tools (pty_*), and edit: deny also denies memory, unless the agent sets a rule for those tools.
• On OpenCode, harnesses/opencode/opencode.jsonc can set a project-wide permission. The starter sets "permission": "allow".

Skills

A skill is a folder of instructions an agent loads when a task needs it. Kortix does not put skill bodies in every prompt.

---
name: triage
description: Classify a support ticket by product area and urgency. Use for every new ticket.
---

# Triage

1. Read the ticket and the customer's last three tickets.
2. ...

• The file is skills/<name>/SKILL.md. Reference files can sit beside it.
• description is what the agent reads to decide when to load the skill. Write when to use it, not only what it is.
• On OpenCode the agent loads a skill with the skill tool. On pi the system prompt lists each granted skill’s name and description, and the agent reads the file.
• Create one in Customize → Skills → New: Create in chat, or Create with a form, which commits a SKILL.md to the default branch.

Which skills an agent may load. The agent’s skills grant compiles onto its permission.skill rule:

When skills is set, it replaces any permission.skill rule in the agent file.

Where skills come from. A session looks in these directories, in order. The first skill of a name wins.

1. The managed kortix-* skills.
2. skills/.
3. .kortix/opencode/skills/ (older projects).

pi also reads harnesses/pi/skills/ after these.

Managed skills. Kortix copies 12 skills into every session when it boots: kortix-cli, kortix-apps, kortix-computer, kortix-connectors, kortix-drives, kortix-harness-refinement, kortix-marketplace, kortix-memory, kortix-onboarding, kortix-slack, kortix-system and kortix-teams. They overwrite a project copy of the same name, so a project cannot override them. A new project commits only skills/kortix-cli. Git ignores the others in the session. A skills list must name each kortix-* skill the agent needs.

Read the managed skills from any terminal. The signed-in host serves them, so they match that host’s version:

kortix system-skills                          # list them
kortix system-skills get kortix-system --full # one skill with every reference file
kortix system-skills file kortix-system <path>   # one reference file
kortix system-skills path kortix-cli          # the skill's folder on disk

kortix skills is an alias. Optional skills come from the marketplace (kortix marketplace list --type skill). See Install from the marketplace.

Sessions read only the directories in the list above, not .claude/ or .agents/. In a local checkout, kortix init links the coding tools you pick to the project’s folders: .agents/skills, .opencode, .claude/skills, .claude/agents, .claude/commands and .pi/skills. For Codex, pi and Cursor it also writes a root AGENTS.md pointer. Git ignores all of them.

Give an agent access

Each grant in agents.<name> unlocks one kind of resource:

The first five take the same values:

• all or "*", or a list that contains "*": everything.
• none, "" or []: nothing.
• A list: only those entries.

Set grants in one of three ways. Each one commits kortix.yaml on the default branch and needs project.agent.write. The dashboard and CLI paths need a kortix_version: 2 manifest. On v3, use a change request.

kortix agents scope support --secrets HELPDESK_API_KEY --connectors helpdesk
kortix agents scope support --apps none
kortix agents config support --set 'kortix_permissions=["project.session.read","project.review.submit"]'
kortix agents config support --set 'skills=["kortix-cli","triage"]'
kortix agents config support --json

A change to an agent’s secrets reaches its running sessions at once, or at the latest on each session’s next prompt.

Which agent runs

A session runs one agent. The request picks it, else the project’s default_agent runs:

Default agent. default_agent must name a declared agent that is enabled. Set it in the dashboard, with kortix agents default <agent>, or with PUT /v1/projects/{projectId}/default-agent. Each one commits kortix.yaml and needs a kortix_version: 2 manifest. On v3, set default_agent in kortix.yaml. kortix agents default --show prints it.

Per-agent switches in agents.<name>:

Model. Set model in the agent file, or pin one without a commit:

kortix agents model support <model-id>   # needs project.model.write; applies to new sessions
kortix agents model support --clear      # follow the defaults again
kortix agents ls                         # each agent, its file and its model

How the default is chosen gives the full order between a session’s model, the agent pin, and the project and account defaults.

What an agent may do

An agent acts as itself, not as the person who started it. Kortix creates one service account per agent per project. A governed session authorizes as that service account. The role of the person who starts the session does not apply, so an agent does the same thing whoever runs it.

An agent’s effective permissions are:

kortix_permissions (in kortix.yaml) ∩ its ceiling role (in IAM) − human-only permissions

• kortix_permissions comes from kortix.yaml on the default branch. It is deny-by-default. all means every project permission, including project.members.manage and project.delete.
• The ceiling is a project role an admin binds to the agent. Open Account settings → Projects, pick the project, and select Grant access. Pick the agent under Agents, then pick the Role. See Project access. With no role bound, the Default agent ceiling applies: every project permission except project.credentials.issue. A ceiling never adds a permission.
• Human-only: project.credentials.issue (mint a project token or a project-scoped personal access token). No agent holds it.
• project.read of its own project is always held. project.write needs only the ceiling.
• Account actions are never granted. An agent session’s token is scoped to one project.

Open Customize → Agents → the agent → Kortix permissions to edit the list. Its What this agent can do panel shows the declared permissions, the ceiling role, the human-only permission and the effective set.

Kortix permissions

What each permission allows is in Permissions. kortix validate --scopes prints the live list. An entry that is not on the list fails kortix validate and a change request merge. At runtime Kortix ignores it and applies the rest.

Deprecated names still validate and resolve to their replacements:

Who may run an agent

The person who runs an agent lends it no authority, so the right to run it is the delegation. Kortix checks it when a person creates, starts or prompts a session, switches a session’s agent, or fires a trigger by hand.

Assign an agent on its People page in Customize, or in Account settings → Projects → the project → Grant access. A child session follows the same rule: the person behind the parent session must be able to run the child’s agent. With no person behind it, an agent starts only another session of itself.

Personal resources stay personal

Personal connector accounts, personal secrets, personal provider keys and a person’s own computer reach a session only when both are true:

1. The session runs on behalf of that person.
2. The session is private.

A shared session, a trigger, an email session, a Slack or Teams session with no linked person, and an unattended run reach none of them. A DM with the bot from a linked person is a private session on that person’s behalf. When another person prompts a private session, the session stops acting on behalf of its creator for good.

Changes to agents are governed

kortix.yaml shapes what agents may do, so the same permissions govern a change to it:

1. Merging a change request needs project.gitops.merge.
2. A merge that changes agents or default_agent also needs project.agent.write. A merge that adds, changes or removes a trigger needs project.trigger.create, project.trigger.update or project.trigger.delete.
3. An agent grants only what it holds. When an agent session writes any agent’s grant (the agent editor, the scope routes, or a change request it merges), every permission, connector, secret and App it adds must be in its own effective grant. Narrowing a grant is always allowed.
4. A session pushes only its own branch unless its agent holds project.gitops.ref.any. A push straight to the default branch also needs project.agent.write and the three trigger permissions. See Who can clone and push.

A project on the legacy v1 manifest with no agents declared runs ungoverned: its sessions act as the person who started them.

Read a denial

A refused request answers 403 with a code and the action it checked:

{ "error": true, "message": "This agent's role does not allow \"project.gitops.merge\". Ask an account admin to raise the role bound to this agent.", "status": 403, "code": "agent_ceiling_insufficient", "action": "project.gitops.merge" }

When an agent session merges and Kortix cannot read the manifest, the merge answers 503 with code: "CR_GOVERNANCE_UNVERIFIED" and Retry-After: 5. Retry the merge.

Harnesses: OpenCode and pi

A harness is the agent runtime inside a session’s sandbox. It runs the model loop, calls tools and writes the transcript. Kortix has two: pi, the default, and OpenCode. Both read the same agents/, skills/, root AGENTS.md and kortix.yaml, and every client reads both through the same session API.

Kortix picks the harness when a session is created. A restart keeps the session’s sandbox, so a session keeps its harness and its history. A flag change applies to new sessions.

• pi_harness is on by default. Turn it off to start new sessions on OpenCode. See Feature flags.
• The session daemon’s GET /kortix/health reports harness.id (opencode or pi) and the capabilities the session serves. From the SDK, call kortix.session(projectId, sessionId).health(). A client hides a control whose capability is missing: runtimeSupports in the SDK, useRuntimeSupports in React.

What each harness supports

Both harnesses serve:

• chat turns, streaming and stop;
• the agent file fields (pi ignores options and color);
• per-agent tool access, permission rules and permission requests;
• questions and skills;
• Kortix and project tools;
• the terminal, secrets and the kortix CLI.

The optional features are capabilities:

A pi session answers a request for a feature it does not serve with 501 and code: "feature_not_supported", and /global/config with 404. pi also refuses message part edits with 501. Connectors work on both harnesses through the kortix connectors CLI. pi subagents are general, explore (read-only) and every agent with mode: subagent or all. A pi subagent cannot start another subagent.

pi has one tool OpenCode does not: codemode. The model writes a script that calls the other tools, and only the script’s output returns to it, so one step can run several calls and filter their output. It is on by default; harnesses.pi.codemode turns it off or makes it the only tool. The session view shows a script as its calls, its code and its output. A subagent does not get codemode.

Harness-only files

Each harness reads one directory that the other ignores. A tool that both need is a project tool in kortix.yaml, not a file here. A kortix_version: 3 project reads neither directory: declare its slash commands in kortix.yaml and its plugins under extensions.

The keys are in the kortix.yaml reference. Kortix loads a pi package as published. It does not test third-party packages.