Guardrails
Limits placed around an agent so a bad step cannot do real damage: a restricted set of tools, an approval prompt before dangerous commands, a sandbox, or a branch it can never push to. Guardrails are what make it reasonable to let an agent run unattended.
At a glance
- Purpose
- Cap the damage of a bad step
- Examples
- Tool allowlists, approvals, sandboxes
- Also
- Scoped credentials, branch protection
- Enforced by
- The harness, OS or git host, not the model
- Not a guardrail
- A rule written in the prompt
How it works
Effective guardrails sit outside the model, where a bad decision cannot talk its way past them. Tool permissions decide what the agent can call at all; many harnesses let you allow test and diff commands freely while blocking or prompting for git push, file deletion, or network access. A sandbox, such as a container or VM, limits what an allowed command can touch. Repository rules, like a protected main branch with required reviews and CI, mean nothing the agent does reaches production without a person.
Credentials count too. An agent holding only a read token for the database cannot drop a table, whatever it decides to try. The same applies to API keys for paid services: a spending cap on the key is a guardrail, a note asking the agent to be careful is not.
Why it matters
Without guardrails you have to watch every step, which defeats the point of an agent. With them, the worst outcome of a bad run is a messy branch you throw away. That is what makes it reasonable to start a task, leave it running, and review the result later. Instructions alone do not get you there: Claude Code's own documentation describes CLAUDE.md as context, not enforced configuration, and points to hooks for actions that must be blocked.
Guardrails vs. sandbox
A sandbox is one kind of guardrail, an isolated environment that contains what commands can affect. Guardrails is the wider category: tool allowlists, approval steps, scoped credentials and branch protection. A sandbox alone does not stop an agent from opening a bad pull request; review rules do.
Human in the loop is the related idea from the other side: a person approving specific steps. Approvals are a guardrail, but the strongest setups combine them with limits that hold even when nobody is watching, so a missed prompt does not become an incident.
Example
{
"permissions": {
"allow": ["Bash(npm run test *)", "Bash(git diff *)"],
"deny": ["Bash(git push *)", "Read(./.env)"]
}
}Common mistakes
- Relying on a line like "never push to main" in the prompt, which a confused model or a prompt injection can override.
- Adding so many approval prompts that people click yes without reading them.
- Giving the agent your full personal credentials when the task needs only a narrow, read-only token.
Related terms
Frequently asked questions
Are instructions in a prompt a guardrail?
Not a reliable one. The model can ignore or be tricked out of a written rule, so real guardrails are enforced by the harness, the sandbox or the git host.
How do I let an agent run unattended safely?
Run it on its own branch in an isolated environment, give it only the credentials the task needs, block destructive commands, and require review before anything merges.