Skip to main content

1.8 Access Control for Agents

Granting agents appropriate access to their environment is key to unlocking flows where agents autonomously complete larger pieces of work. This section teaches you the principles and techniques to safely and confidently configure access control for your agentic coding tool, especially in finding the right balance between agent capability and system safety.

Why Access Control Matters​

Agentic coding tools are capable of more than just generating code. They can read information from systems that they're connected to and run actions and commands much like a human developer would. Granting agents access to take these sorts of actions produces better results and expands the type of work that agents can complete autonomously.

For example, agents can:

  • Validate their work by running tests or interacting with the application. This helps ensure the work you review at the end is correct and eliminates hallucinated claims such as that a bug was fixed when it definitely was not
  • Complete development tasks like executing DB migrations or creating commits, which agents may need to be able to do to complete some features end-to-end

The solution however is not to grant agents full access to take any action. Giving an agent too broad of permissions creates risks that the agent takes irreversible, destructive actions or exfiltrates secrets. Thus, configuring access control is about balancing the value of agent autonomy with the risks of agents taking irreversible, destructive actions.

Configuring Access Control​

There are risks with granting too much and too little access to your agents, so you need to identify a sweet spot that best manages these risks

  • Granting too little access will cause friction, requiring you to take actions on behalf of the agent when the agent could have taken the action itself. It can also cause an inundation of permission prompts, which can become overwhelming and cause Approval Fatigue, where permission prompts that should be reviewed closely are lost amongst a large volume of permission prompts that can be safely approved. As a result, permission prompts are reflexively approved, and destructive actions are inadvertently approved
  • Granting too much access allows the agent to perform destructive actions like deleting a production database and increases the risk of security incidents, like exposed secrets. LLMs are non-deterministic and susceptible to prompt injection attacks, so if your agent has the ability to perform a destructive action, a bloated context window or malicious instruction could cause the agent to perform the action, even if you've provided instructions not to
  • Granting an appropriate level of access ensures that the agent can perform safe actions autonomously, and permission prompts are primarily those that truly require human review. This balances agent autonomy and system safety

Spectrum of AI agent access from too restrictive to too permissive

Choosing Your Access Control Posture

There is no single "correct" way to configure access control. Every configuration decision has tradeoffs in terms of risk, friction, and capability. It's more important that these tradeoffs are made deliberately than that the system is as secure as possible.

Principles of Agent Access Control​

The AI tooling space changes quickly, so specific configurations and approaches may be quickly irrelevant. The following are principles that apply regardless of how exactly access control is configured.

  • Prefer Deterministic Access Control: When possible, prefer access control approaches that deterministically define what actions an agent can or cannot take. LLMs are non-deterministic and susceptible to prompt injection attacks, so prompt-based permission definitions can be bypassed if the context becomes diluted or contains a malicious instruction
  • Principle of Least Access: Grant agents the smallest amount of access that they need to perform their task. This principle is often applied to human users, but applies to agents for the same reason: it prevents the execution of destructive actions, especially accidentally or by malicious actors that gain access to a system
  • Defense in Depth: For critical security risks, don't rely on a single security control to enforce a policy. For example, if you have a method to prevent an agent from reading secrets, you should also have a method to prevent exfiltration in case a secret is somehow read
  • Isolation and Reversibility: Identify strategies to isolate the changes that agents make from production systems and from other agents, as well as to make changes reversible. This makes it safe to grant broader access. Common industry tools already allow this but their value increases in this context. For example, version control (i.e. git), git worktrees, containers, and ephemeral service instances

Components of Agent Access Control​

Access control for your coding agent is primarily controlled via two related, complementary approaches:

  • Sandboxing isolates the agent and the actions it can take, defining hard boundaries for the environment that the agent operates in
  • Permissions provide guardrails for what actions the agent can take within its environment

You typically want to consider how you can configure both sandboxing and permissions for your agentic coding tools. Each excels at providing certain types of protection and when used together, they provide defense in depth.

Sandboxing: Environment Boundaries​

Sandboxing refers to techniques that isolate the agent in an execution environment, rather than directly running the agent on a machine. This may involve using OS-level sandboxing features, containers, virtual machines, or a hosted sandboxing platform.

Regardless of the approach, sandboxing isolates the filesystem, network, and computing resources that the agent has access to from the host machine, reducing the "blast radius" if something goes wrong. For example, granting a sandbox access to just a repository directory makes it impossible for the agent to destroy other files on the host machine if a malicious instruction entered the agent's context.

Characteristics of Sandboxing:

  • Low flexibility/granularity: you enable/disable broad categories of actions that can be taken in the environment, but you often can't specify small details. For example, you may be able to set which hostnames the environment can interact with, but not restrict the particular payloads sent to those hostnames
  • Low complexity: typically requires relatively simple configuration to define the filesystem, network, and compute resources the environment has access to. You don't need to consider many smaller options and controls like with permissions
  • Complemented well by permissions which can provide more granularity for actions as necessary. For example, to prevent destructive actions against hostnames that are otherwise allowed by the sandbox

Permissions: Environment Guardrails​

Permissions refer to guardrails on the actions that the agent can take within its environment. This includes restrictions on what bash commands, MCP tools, or other harness tools the agent can use, not use, or must request permission to use.

Characteristics of Permissions:

  • High flexibility/granularity: permissions typically allow you to configure specifics of what tools the agent can use, down to the specific arguments and flags that it can pass in bash commands
  • High complexity: because commands and tools often have many arguments and there may be multiple ways to accomplish a task with different commands or arguments, properly configuring permissions can be a difficult task
  • Complemented well by sandboxing which can provide defense in depth for any permissions mistakes. For example, to ensure that the agent cannot access certain hostnames, just in case you've missed an unexpected command or argument the agent could leverage to access the network

Permissions in Claude Code​

As you're configuring permissions, start restrictive and gradually grant permissions as Claude requests to perform actions that you feel are safe. This ensures that the Principle of Least Access is applied, since it's much more difficult to start permissive and reduce permissions.

See Claude Code Documentation for more information.

1. Exploratory Starting Point: Auto Mode​

Claude Code's auto mode automatically classifies whether commands are safe, reducing or eliminating permission prompts. If you haven't granted Claude permissions to run commands as it works, it can be a good place to start to get a sense for what it can do when given more autonomy.

Use Auto Mode Cautiously

Auto mode uses an LLM to classify whether commands are safe to run, meaning permissioning is non-deterministic and could result in destructive or unexpected actions. For example, the defaults allow Claude to read secrets from .env files. Treat auto mode as a way to explore agent autonomy in low-stakes environments, not as a substitute for explicit, deterministic permission configuration on real projects.

2. Accept Edits Mode​

By default, Claude Code starts in a mode that requires approval to make changes to files in your repository. Enable acceptEdits mode to allow Claude to autonomously make changes to files, and run commands to create, copy, or move files within the repository.

Version control systems like Git help isolate these changes and make them reversible. Structured workflows like SDD help in producing a plan that allows agents to use this mode effectively. Identifying an appropriate scope of work and aligning on the approach before making changes ensures that it's feasible to review the larger set of changes produced at the end.

3. Allowing Commands​

You can grant Claude permissions to run bash commands without a permission prompt. The allow list can include glob patterns with * to allow a set of commands matching the provided pattern. For example, git commit * allows Claude to execute git commit with any flags or options.

Be Careful with Wildcards

Using a glob in the allowlist is very permissive, allowing Claude to run the command with any arguments or flags. For example, npm run * allows Claude to run any script defined in package.json, but if Claude can edit that file, it effectively allows Claude to run arbitrary commands. Make sure you understand all forms of the command you are allowing, and prefer a more specific list of allowed commands when possible.

Controlling Command Structure

Claude may execute the same command in different forms, or generate unusual one-off commands to log data, which create a permission prompt for a command that would otherwise be approved. Update your AGENTS.md or other prompts to explain the preferred command structure, to address this problem.

4. Deny/Ask Permission Configuration​

In addition to a list of allowed commands, Claude allows you to configure commands that are automatically denied or that always require approval from the user.

From the Claude Code Documentation:

Rules are evaluated in order: deny -> ask -> allow. The first matching rule wins, so deny rules always take precedence.

For example, you could allow git push *, but deny git push --force * to better control how agents are allowed to push changes.

5. Custom Hooks​

Hooks are user-defined shell commands that execute at specific points in the Claude Code lifecycle. PreToolUse hooks intercept bash commands before execution and can make a deny/ask/allow decision with a reason for the agent to read.

Although not strictly part of Claude's permissioning system, custom hooks provide a more granular way to control permissions than wildcards and deny/ask/allow lists can provide. You could, for example, write a script that only allows force pushing to feature branches, something that may be difficult to do with wildcards alone.

For complete information on PreToolUse hooks, see the Claude Code Hooks documentation

Sandboxing in Claude Code​

Sandboxing is a less established feature in Claude Code, but there are plenty of options to explore. You should explore the available sandboxing features to get a sense for their abilities.

See Claude Code Documentation for more information.

Bash Sandbox​

Claude Code's native sandboxing feature provides filesystem and network isolation for Bash tool execution. The restrictions you define will apply to all bash commands that Claude runs, and their subprocesses. This means if Claude writes a creative script to access a part of the filesystem or network you tried to restrict via permissions, the action will fail.

Bash Tool Isolation Only

The bash sandbox only sandboxes commands run via the Bash tool. This means that execution of built-in tools, MCP tools, or plugins may still be able to access parts of the filesystem or network that you restricted via the sandboxing config. For complete sandboxing of Claude Code, see the section on containers below, or Anthropic's Sandbox Runtime for an experimental approach for sandboxing Claude Code without containers

Note that the incomplete sandboxing is beneficial in some contexts, as it means that commands that can't run in the sandbox can still be run outside the sandbox (e.g. if the agent wants to spin up a docker container). Claude Code allows "unsandboxed fallbacks", which means that commands that fail in the sandbox are attempted again outside the sandbox, with your configured permissions.

How to use: Run the /sandbox command in your Claude Code session. Configure "regular permissions" mode unless your sandbox mode is restrictive enough that Claude should be allowed to execute any command in the sandbox. Grant the sandbox write access to additional directories as necessary and restrict read access, which by default includes almost all files on your machine. Allow network access by hostname as Claude Code prompts you.

When to use: As an initial introduction to sandboxing when you need to explore what actions can or cannot be executed in the sandbox in your use-cases. And in cases where sandboxing of bash commands alone is sufficient.

Containers​

Containers are a development primitive that provide filesystem, networking, and resource isolation. By running your Claude Code agent within a container, the agent is isolated by the restrictions you apply to the container. Dev containers are a useful tool for building these sorts of containers.

How to use: Build and run a container with Claude Code installed however you prefer. To get started quickly, you can use Docker sandboxes. Also see Anthropic's documentation on installing Claude Code in a dev container

When to use: You want strong isolation from your host machine and have the desire to configure sandboxing yourself.

Claude Code On The Web​

Claude Code On The Web runs your session in Anthropic-managed cloud infrastructure, rather than on your own machine. It is only available to certain classes of users, so check documentation for the latest on if the feature is available to you.

The session accesses your code from GitHub rather than from your filesystem directly and network access is restricted by default (but configurable).

How to use: Start a cloud session by running claude --cloud "<task description>" or via the "Code" tab in Claude Desktop and claude.ai

When to use: You want strong isolation from your host machine and you don't wish to configure containers or other sandboxing infrastructure yourself.

Secret Management​

Agents introduce a new vector for secret exfiltration, which makes standard secret-management practices more important and requires new techniques for managing secrets during development.

Developer machines typically contain secrets in plain text that are used during development. The assumption was that if a malicious actor gained access to the filesystem to steal these secrets, there were far more serious security issues at play. However, the introduction of AI agents introduces dozens of ways that sensitive information can be exfiltrated from a machine, especially via prompt injection.

The Lethal Trifecta provides a model for understanding and preventing these issues. If an agent has access to sensitive information, exposure to untrusted content, and the ability to communicate externally, then the untrusted content can instruct the agent to externally communicate the sensitive information to a malicious actor.

The following sections provide techniques for addressing each component of the lethal trifecta

1. Limit Agent Access to Secrets​

Minimize opportunities for agents to access plaintext secrets in the first place

  1. Use local secret management tools that let you avoid storing plaintext secrets in .env files, which an agent can read. Tools like Infisical or Varlock are examples that you might use as a starting point
  2. Configure permissions so that the agent cannot run commands or read files that expose secrets
  3. Use sandboxing for OS-level enforcement that prevents agents from reading secrets
Limitations

There are limits to restricting access to secrets in the context of AI coding agents. If the agent is running an application that uses a secret, it could simply modify the code to log the secret, even if the secret were protected otherwise.

2. Controlling External Communication​

Prevent an agent from exfiltrating a secret if it does gain access to one

  1. Configure permissions so that agents can only autonomously make external requests to trusted sources, and other requests are reviewed by a human
  2. Use sandboxing for OS-level enforcement that prevents agents from communicating with untrusted external sources

3. Using Trusted Sources​

Prevent an agent from receiving adversarial instructions that could trigger it to exfiltrate a secret. Prefer granting agents access to trusted sources of information that are unlikely to contain adversarial instructions

This is the most difficult to control and review since even trusted sources may contain adversarial instructions, and the volume of content that agents consume makes thorough review impossible.

Knowledge Check​

Question 1 of 7

Permissions and Security Knowledge Check

Q1. A team grants their agent very few permissions, resulting in constant approval prompts. What risk does this create?