> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2501.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling Permissions

> Limit agents at the credential and provisioning layer, not just the prompt

Via [Credentials](/0.8/configure/credentials) and controlled provisioning on target machines, you can hard-cap an agent's blast radius — independent of what the prompt says.

## The credential layer

When an agent SSHs into a Linux machine, it does so as a specific user. Give it the **least-privileged user** that still gets the job done.

A common pattern: create an `agent-2501` user on each managed host with only the permissions agents need. Critical commands (package installs, service restarts on specific units) go via `sudoers` allowlists.

Every authentication layer — SSH, WinRM, MCP, API keys — can be scoped:

| Layer                       | How to limit                                                                        |
| --------------------------- | ----------------------------------------------------------------------------------- |
| SSH                         | Dedicated user + restrictive `sudoers`                                              |
| WinRM                       | Local user with explicit RBAC; gMSA for fine-grained AD-bound privileges            |
| Cloud CLI (AWS, GCP, Azure) | IAM role attached to the credential — e.g. `ec2:ReadOnly*` for read-only EC2 agents |
| API tokens (3rd-party)      | Scoped tokens per integration; never reuse a production token in a read-only agent  |
| MCP servers                 | RBAC inside the MCP — the MCP itself can enforce read-only tool variants            |

## Match permissions to the agent's mission

If an agent only needs to read AWS EC2 to produce a resource report, give it an IAM role with **`ec2:Describe*`** only. The agent literally cannot terminate an instance with that role, no matter what the prompt says.

This is the most reliable safety layer in the system. Prompts can be jailbroken; IAM cannot.

## When to relax

As you grow confident in an agent, you may want to give it more capability. Two things to update **together**:

1. **The credential's permissions** — broaden the IAM role, add `sudoers` entries.
2. **The specialty and rules** — the agent was previously prompted that dangerous operations are out of scope. Update that text to reflect what's now allowed and what's still off-limits.

Promote permissions and prompt together. A relaxed prompt with locked-down creds frustrates the agent into retry loops; relaxed creds with a strict prompt is a footgun waiting to fire.

## Quick checklist

* [ ] Each host has a dedicated `agent-2501` (or equivalent) user — not root, not the human admin
* [ ] Sudo entries are explicit allowlists, not `NOPASSWD: ALL`
* [ ] Cloud credentials use scoped IAM roles, not long-lived admin keys
* [ ] Read-only investigation agents have IAM/RBAC matching their mission
* [ ] When you promote an agent's capability, you update both creds **and** prompts