Set Up permissions.yaml

Kiro checks every file read, command run, and MCP call against your permission rules before it happens. permissions.yaml is where you write those rules, and a few deny lines buy more safety than any amount of careful prompting.

When to use this

Set permissions before you let an agent run unattended: in Autopilot, in a headless CI job, or as a background agent. Also set them on any repository that touches production, money, or customer data. On a personal side project the defaults are reasonable and you can leave them alone.

Steps

1. Find the right file. Personal rules that follow you everywhere go in ~/.kiro/settings/permissions.yaml. Rules for one project go in that workspace’s file at ~/.kiro/workspace-roots/<hash>/permissions.yaml. Note that the workspace file lives outside the repository on purpose, so cloning a repository cannot grant it permissions.

2. Pick the capabilities you care about. The list is fs_read, fs_write, shell, web_fetch, web_search, mcp, subagent, skill, power, context, diagnostics, and sandbox_network. The meta capabilities all, builtin, and filesystem cover groups at once.

3. Choose an effect for each: deny, ask, or allow. The order is fixed. Deny beats ask, ask beats allow, and deny wins regardless of which scope it came from.

4. Write the rules. A rule takes a match glob and an optional exclude glob, so you can allow a capability broadly and carve out the parts you do not trust.

   Example: ~/.kiro/settings/permissions.yaml

   # Illustrative shape only, using the documented capability names,
   # effects, and rule keys. Confirm the exact layout for your version
   # at kiro.dev/docs before you rely on it.
   web_fetch: deny
   shell: ask
   fs_write:
     ask:
       match: "**"
       exclude: "infra/**"

5. Choose the scope deliberately. Kiro has six: its own hardcoded rules, administration, user, workspace, agent, and session. A rule you want everywhere goes at user scope. A rule for one persona goes at agent scope.

6. Answer approval prompts with intent. Each prompt offers Allow, Deny, Always allow, and Always deny, and the persisted answer can apply to all workspaces, this workspace, or this session.

7. Set the IDE autonomy separately. Settings, Agent, Agent Autonomy (kiroAgent.agentAutonomy) switches between Autopilot and Supervised. That controls how often the agent pauses; permissions control what it can do at all.

Check it worked

Ask the agent to do something you denied. It should refuse rather than prompt you, because deny does not offer a way through. Then ask for something set to ask and confirm the prompt appears with the four options. Finally, run the same request in a different workspace and check the rule applied at the scope you intended.

Common problems

• A deny rule blocks more than expected. Deny wins everywhere, so a broad deny at user scope cannot be relaxed for one project. Move it to workspace or agent scope.
• You edited the wrong file. Workspace rules are under ~/.kiro/workspace-roots/<hash>/, not in the repository. Editing a file in the repo does nothing.
• You clicked “Always allow” once too often. The persisted answers are rules too. Review them when the agent stops asking about something it should ask about.
• Autopilot feels unsafe. It should, without permission rules. Deny fs_write outside your source folders and shell outright, then reconsider.
• Secrets are still readable. Permissions govern capabilities, not file lists. Use .kiroignore to keep files out of the agent’s reach.

Related

• Build a read-only reviewer agent applies deny rules to one persona.
• Keep secrets out with .kiroignore is the file-level control.
• Agentic development explains where the permission check sits in the turn loop.