Permissions and YAML policies

Choose what an agent may read, change, execute and fetch. Shared YAML policies let administrators apply the same defaults and restrictions across an organization or team.

Agent permissions

Rule	Example	Meaning
Path, Read	`/var/log/my-app/**`	Read matching files without editing them.
Path, Write	`/tmp/codity-policy-test/out/**`	Read and change matching files.
Command	`git status`	Run a matching command through the agent's shell tool.
URL	`https://example.com/**`	Fetch matching URLs through the agent's fetch tool.
Never allowed	`/tmp/codity-policy-test/blocked/**`	Deny matching access. A filesystem deny blocks reads and writes.

Use absolute paths to avoid ambiguity, especially outside a Git checkout. Relative paths are interpreted from the folder where the agent starts; the runner translates them to its project root. Quote paths containing spaces in task instructions and shell commands.

New agents receive visible default deny rules for credential folders, environment-printing commands and dangerous system commands. Review these on the agent page. A prompt such as "never access secrets" does not create a permission rule; add a deny or shared policy.

Refuse rejects unlisted actions immediately. Ask me creates a permission request and pauses that tool call. You can allow it once, for the current run, or permanently, or deny it. The default request timeout is 15 minutes. Shared denies cannot be approved away.

Commands are a separate grant from paths. Allowing file access does not allow cat, ls or another shell command. Conversely, interpreters, package scripts, launchers and similar commands can operate using the machine's permissions. Broad command grants require an explicit acknowledgement in the agent form; shared policies reject such allow rules. Prefer narrow tool access and restrictive machine permissions.

Where to edit shared policies

Organization: open Settings and find Agent policy.
Team: open Teams, select the team, then open Settings and Agent policy.

Only account administrators can edit and save these policies. Other users can read them. A test team is not created automatically; create it in Teams if you want one, then select it explicitly on the agent creation form. Merely selecting a team in the dashboard navigation does not assign an agent to it.

Paste YAML, select Review changes, then Confirm policy changes. Reload policy loads the saved revision. If another administrator saves first, reload and review their changes before saving yours.

YAML format

version: 1
permissions:
  - path_pattern: /tmp/codity-policy-test/input/**
    kind: filesystem
    access: read
    effect: allow
  - path_pattern: /tmp/codity-policy-test/out/**
    kind: filesystem
    access: write
    effect: allow
  - path_pattern: /tmp/codity-policy-test/blocked/**
    kind: filesystem
    access: read
    effect: deny
  - path_pattern: "printf POLICY_OK*"
    kind: bash_command
    access: read
    effect: allow
  - path_pattern: "printf DENIED*"
    kind: bash_command
    access: read
    effect: deny
  - path_pattern: "https://example.com/**"
    kind: webfetch_host
    access: read
    effect: allow
  - path_pattern: "https://example.com/private/**"
    kind: webfetch_host
    access: read
    effect: deny

Field	Allowed values
`version`	Integer `1`.
`permissions`	A list of rules; use `[]` for an empty policy.
`path_pattern`	A path, command or URL pattern, maximum 1,000 characters. Quote command and URL patterns.
`kind`	`filesystem`, `bash_command` or `webfetch_host`. Defaults to `filesystem`.
`access`	`read` or `write`. Required. Use `read` for command and URL rules.
`effect`	`allow` or `deny`. Defaults to `allow`.

Unknown fields and unsupported versions are rejected. Policies allow at most 400 rules and 64 KiB of YAML. To remove a shared policy's rules, save version: 1 with permissions: []; organization policies and agent-specific rules still apply.

Inheritance and timing

An agent receives its organization's rules, its selected team's rules and its own rules. Shared allows act as defaults. Shared denies always win, including against a more specific agent allow and an Ask me approval.

Each new run or resumed session picks up the current shared policy revisions. Saving a policy does not change the permission snapshot of an already running agent. Pause and resume a recovery-enabled session, or start a fresh run, to apply it.

Test the policy

Prepare disposable files on the machine where the agent will run:

mkdir -p /tmp/codity-policy-test/input /tmp/codity-policy-test/out /tmp/codity-policy-test/blocked
printf 'ERROR database timeout\nERROR upstream unavailable\n' > /tmp/codity-policy-test/input/app.log
printf 'PRIVATE_TEST_DATA\n' > /tmp/codity-policy-test/blocked/private.txt
cd /tmp/codity-policy-test

Save the sample YAML on a team named agent-policy-test. Create an Interactive agent assigned to that team, choose Refuse, and leave its task and individual permissions empty. Supply a valid provider/model key and run its generated install command from this folder.

Ask each question separately:

Ask the agent	Expected result
Read `/tmp/codity-policy-test/input/app.log` and write both error lines to `/tmp/codity-policy-test/out/summary.md`.	Reads the log and creates the summary.
Overwrite `/tmp/codity-policy-test/input/app.log` with `CHANGED`.	Refuses the write; the original log stays unchanged.
Read `/tmp/codity-policy-test/blocked/private.txt`.	Refuses and does not reveal `PRIVATE_TEST_DATA`.
Run exactly `printf POLICY_OK`.	Runs and prints `POLICY_OK`.
Run exactly `printf DENIED`.	Refuses.
Fetch `https://example.com/`.	Permission allows the fetch; network or server failure can still occur.
Fetch `https://example.com/private/test`.	Refuses before fetching.

To test deny precedence, create a second agent in the same team with an individual Write allow for /tmp/codity-policy-test/blocked/**. The read must still be refused. Ask me must also refuse that shared deny without offering an approval that bypasses it.

Verify the log and summary from your own terminal. Change a team rule and save it; then start a new run or resume before testing the updated rule. The existing running session keeps its previous policy snapshot.

PreviousCreate your first agent NextPause and resume agent sessions