# AI agent permissions and policy in an open source platform

> AI agent permissions decide what an agent can read, run and change without a person. In Kortix, the open-source AI Operating System, those rules are files in one git repo you own, so every grant and every policy is reviewable as a diff.

URL: https://opensourceaiagentplatform.com/ai-agent-permissions-and-policy

## Where an agent's grants live

`kortix.yaml`

```yaml
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]
```

Source: https://kortix.com/docs/project/agents

The kortix.yaml block that declares one agent and everything it may reach. Values never appear here.

## What AI agent permissions control

An AI agent permission is a rule that decides whether one agent action runs on its own, waits for a person to approve it, or is refused. Kortix turns those rules into files. The same files hold the grants that decide what the agent can reach outside its own sandbox, which the [sandboxing page](/ai-agent-sandboxing) explains: which connectors, which secrets, which skills, and which Kortix permissions. Because they live in the project's git repo, you can read them, diff them and roll them back like any other change, and you can grep a whole company for every place an agent is allowed to act.

Two layers do the work. The behavior layer is the agent file, `agents/<name>.md`, and it carries the tool rules. The governance layer is the `agents.<name>` block in `kortix.yaml`, and it carries the grants. A version 2 project keeps the two apart: the markdown file says how the agent thinks, and the manifest says what it may touch.

## Where the policy lives: one repo, plain files

Everything an agent may do is text in one repo. An agent is a markdown file plus a block in the manifest. A skill is a folder with a `SKILL.md`. Memory is plain files. Connectors, triggers and the machine image are declared in `kortix.yaml`. No settings screen hides the rules. The dashboard writes the same files a person would edit by hand, and the [management page](/ai-agent-management) reads that same repo.

Grants are deny-by-default. An agent with no `connectors`, `secrets`, `apps` or `kortix_permissions` key gets none of them. That default matters, because a new agent starts with nothing and earns access one grant at a time. An omitted `tools` key is the exception that grants every tool, so review it on any agent you inherit.

## Scoped connectors and server-side credentials

A connector grant names the exact apps an agent may call. `connectors: [helpdesk]` admits one app and nothing else. The credential behind that app does not sit in the agent's machine: connector credentials are brokered server-side and never enter the machine, so a logged environment dump cannot leak the key. When an agent needs a value that is not a connector, you grant a secret by name, and the value is encrypted at rest with a key per project. The manifest lists the name, never the value.

This is the difference between handing an agent an API key and letting it ask for one call. If you are weighing how much access to hand over, [How to give AI agents tool access safely](https://kortix.com/blog/secure-ai-agent-tool-access) works through the trade-offs.

## Allow, Ask, or Block, down to the argument

A connector policy decides what happens to each action. Allow runs it, Ask holds the call until a person approves it, and Block refuses it. A policy matches an action by pattern, so read calls can flow and a destructive call can stop. A single connector can carry several rules, and the first match that fits the call wins.

Kortix also lets the rule reach further than the connector. The agent file's `permission` block takes `allow`, `ask` or `deny` for each tool, and you can match on the command itself. One agent can run `git status` freely, ask before any other shell command, and be denied `rm -rf *`. The rule matches the command the agent actually typed. A tool whose rule denies every call is removed from the agent's tool list.

## Approval gates and the merge gate

Two gates decide whether an agent's work goes live. The first is the approval gate: when a policy says Ask, the turn pauses, a person approves or rejects the call, and the agent resumes. Approval gates you set. Off until you set them, which is why the first job on a new project is deciding which calls deserve an Ask. The second is the merge gate. An agent works on its own branch and opens a change request. A person with the `project.gitops.merge` permission reviews the diff and merges it. Merge is default-deny for agents. A session can merge its own change request only when its agent's grant includes that permission, so you can keep a person in the loop for every landing.

An agent can edit its own configuration on its session branch and propose the change. A person approves it. That is how a company file patches against itself without letting an agent rewrite its own limits. You can run all of this on your own server, and the [self-hosting page](/self-hosting) covers the install.

## How this compares with other platforms

Other open-source agent platforms document access control, and the shape of the controls differs. OpenHands Enterprise documents SAML single sign-on, multi-user RBAC and centralized audit logs, and it runs agents in sandboxed environments; its permissions act at the account and platform level. Dify documents workspace roles and per-resource permissions, so a member's rights come from a role plus what each app or knowledge base allows. n8n documents three built-in instance roles and project-level RBAC on top of them. Kortix puts the agent's own reach in the repo beside the agent, and controls each connector call as well as the account.

## What to check before you turn agents loose

Work through six checks and you have a policy worth reviewing:

- Start with no grants and add them one at a time.
- Give each agent its own connector set instead of one broad shared grant.
- Put Ask on the calls that move money, send messages or delete data.
- Decide who can use each secret, and keep personal values out of shared sessions.
- Leave the merge gate at its deny-by-default so a person reads every landing.
- Read the audit trail: every action is recorded, and the per-session audit view is an Enterprise entitlement.

State that sticks across sessions is what turns a scoped agent into a useful one, and the [agent memory and state page](/agent-memory-and-state) covers how that works.

_FAQ_

## Controlling what agents can reach

### Who can read the value of a secret an agent uses?

The value is write-only: no page, API route or CLI command returns it. A session receives a value only when the person who started it and the agent's grant both allow it, and connector credentials are brokered server-side and never enter the machine.

### Can an agent merge its own work or change its own rules?

An agent can edit its own configuration on its session branch and propose the change, and a person approves it. Merge is default-deny for agents, so a session can merge its own change request only when its grant includes the merge permission.

### How do I stop one agent from using a connector another team owns?

Grants are deny-by-default and name connectors one by one, so an agent with `connectors: [helpdesk]` cannot reach an app it was not given. Set a connector policy to Ask or Block where a call needs a person or must never run.

### What happens when an agent tries an action it is not allowed to take?

A policy of Ask pauses the turn until a person approves or rejects the call, and the agent resumes after. A policy of Block refuses the call outright, and a tool whose rule denies every call is removed from the agent’s tool list.

### Is the policy set per project or per account?

The agent, connector and secret rules live in the project's `kortix.yaml` and its agent files. Account roles, groups and project grants decide who can reach the project and its agents in the first place.

## Set the rules before the agents run

One repo holds every grant, policy and approval gate.

[Try Kortix](https://kortix.com) · [Read the docs](https://kortix.com/docs)