An agent that can run shell commands is a user with a very fast keyboard and no common sense. It can read any file the operator can read. It can write any file the operator can write. It can call any network endpoint the operator's machine can reach. It can run any binary installed on the system. And it will do all of these things faithfully, according to its instructions, even when the instructions are wrong — or when the instructions were fine when written but the situation has changed.

The sandbox is not a wall. It is a set of practices that makes the agent's failures recoverable. This piece covers the threat model, the five defensive practices, and the recovery playbook.

The threat model

The starting point for any safety discussion is the threat model: what can actually break, and how badly?

What an agent with shell access can do, if it runs the wrong command:

  • Read any file the operator can read. This includes credentials stored in plaintext files, session tokens in environment variables, private keys, and the contents of any project folder the operator has access to.
  • Write any file the operator can write. This includes overwriting configuration files, corrupting workspace files, deleting the agent's own memory, and filling disk space.
  • Call any network endpoint the operator's machine can reach. This includes external APIs, email servers, webhooks, cloud provider endpoints, and any service that accepts connections from the operator's IP.
  • Run any binary installed on the system. This includes system utilities, developer tools, container runtimes, and anything that can be downloaded and executed.

The implication is direct: a confused or compromised agent is a confused or compromised operator. The agent does not have a separate permission layer. It runs as the operator, with the operator's filesystem access and network access.

The three blast radii

The damage an agent can do groups into three blast radii, each requiring its own defense.

Local filesystem. The agent works in a directory tree. If it can read everywhere the operator can read, it can read credentials files, private documents, and workspace files it was not supposed to touch. If it can write everywhere the operator can write, it can overwrite config files, corrupt project directories, and fill the disk.

Credentials. API keys, OAuth tokens, SSH keys, database passwords — any secret that lives on the machine the agent runs on is a credential the agent can potentially access. If the agent can exfiltrate a credential, it can use that credential from anywhere, not just from the machine it runs on.

External side effects. The agent can send email, post to the web, call external APIs, trigger deployments, and make financial API calls. These side effects happen in the real world, not on the local machine, which means the damage is not limited to what the agent can undo by deleting a file.

The evaluation, safety, and governance piece covers the broader governance context — including the governance ladder that applies when agents scale from personal to team to business deployments.

Local filesystem blast radius

The first defense is workspace isolation. The agent works in a specific directory tree — its project folder — and the operating instructions tell it to treat anything outside that tree as read-only or inaccessible. In practice, most agent runtimes enforce workspace isolation at the runtime level, not at the instruction level. The operator does not rely on the agent to decide where it can write; the operator configures the runtime to only expose the project directory.

The second defense is output isolation. The agent writes to a specific output directory, not anywhere in the filesystem. Generated files, build outputs, and delivery artifacts all go to a designated location. The agent does not write to system directories, config directories, or application directories unless explicitly instructed to by the operator.

The third defense is the git-snapshot pattern. Every change the agent makes to a tracked file is recoverable via git checkout. The operator can revert the workspace to the state before a bad run. The requirement is that the workspace is a git repository and the operator has not discarded the history. The git-snapshot pattern is covered in the workspace organization piece.

Credentials blast radius

The first defense is the keychain. Secrets — API keys, OAuth tokens, database passwords — live in the OS keychain, not in files the agent can read. The agent retrieves a secret from the keychain at the moment it needs it, uses it, and never writes it to disk in plaintext. Most modern agent runtimes support a keychain integration; the alternative is environment variables populated at session start.

The second defense is the env-var-with-no-echo pattern. A secret in an environment variable is available to the agent but not visible in process listings or log files. The agent retrieves the variable, uses it for the API call, and never logs the value. The operator sets the variable; the agent consumes it; the value never appears in any file the operator might later audit.

The third defense is the scope principle. An API token should have the minimum required scopes. A read-only API key should not have write permissions. A token scoped to one service should not have access to another. If the agent's token is compromised, the blast radius is limited to what that token can actually do.

The human-in-the-loop glossary entry covers the approval patterns for actions that escape the sandbox — the human gate that prevents the agent from making irreversible external calls without review.

External side effects

The first defense is the dry-run by default pattern. The agent drafts the action — the email, the API call, the deploy — and presents it to the operator for review before executing. The draft is a preview, not a commitment. The operator approves, edits, or vetoes before anything happens in the real world.

The second defense is the idempotency-key pattern. Every external side effect — an email send, an API mutation, a file write to an external service — gets a unique key before it fires. If the workflow runs again, it checks for the key before re-firing. A retry that arrives after a successful run is skipped. This prevents double-sends, double-charges, and duplicate deploys.

The third defense is the rate-limit pattern. The agent is configured with a maximum number of external calls per minute. If the rate limit is reached, the agent pauses rather than continuing to fire. The rate limit is not a performance optimization — it is a safety net that prevents a looping agent from making hundreds of calls in a short time.

The observability glossary entry covers the signal capture that makes external side effects auditable. You cannot recover from what you cannot see.

The sandbox as a discipline

The sandbox is not a wall. It is a set of five practices that compose. Workspace isolation prevents the agent from reaching places it should not. Keychain storage prevents credentials from living where the agent can exfiltrate them. Dry-run by default prevents external side effects without review. Idempotency keys prevent duplicates. Rate limits prevent burst behavior.

None of the five practices is sufficient alone. Workspace isolation without keychain storage means the agent can still read credential files if it knows where to look. Keychain storage without dry-run means the agent can still fire external calls without review. Dry-run without idempotency keys means a re-run of a workflow that already fired will double-fire. The practices compose, and they all need to be in place for the sandbox to hold.

The second thing to understand is that the sandbox is the operator's responsibility. The agent does not design its own sandbox; the operator does. The operator decides what the agent can read, write, and call. If the sandbox fails, it is because the operator did not design it correctly.

The third thing to understand is that the sandbox is not a one-time configuration but an ongoing practice. The operator reviews the sandbox posture when the agent gains new capabilities, new credentials are added, or the agent gets new external APIs to call. A sandbox correctly configured six months ago may be inadequate today.

When the sandbox fails

The recovery playbook has five steps, in order.

Stop the agent. Terminate the running session. If the agent is running as a cron or a background process, stop the process. The agent should not be allowed to continue operating while the operator investigates.

Audit the file changes. Run git status and git diff on the workspace. Identify every file that was changed during the failing run. Revert the changes that are clearly wrong — overwrites, deletions, corrupt files. Preserve the changes that are ambiguous until they can be reviewed.

Rotate the credentials. If the failure involved credential exposure — the agent read a file it should not have, or accessed an API it should not have — rotate the credential immediately. Generate a new key, update the keychain or environment variable, and revoke the old key. Do not wait to see whether the credential was actually exfiltrated.

Review the external side effects. Check the logs for API calls, emails, webhooks, and deploys that fired during the failure window. For each one, determine whether it was intentional or accidental. For accidental ones, undo what can be undone and notify affected parties for what cannot be undone.

Write a postmortem. The postmortem is not about blame. It is about the question: which practice in the sandbox failed, and how do we close that gap? If the agent read a credential file, the gap is that the credential file was in the workspace. If the agent fired an unauthorized API call, the gap is that dry-run was not in place. The postmortem names the gap and names the fix.

The discipline is to treat every failure as a system bug, not an agent bug. The agent did what it was instructed to do. The instruction set was wrong, or the sandbox was incomplete. The fix is in the system, not in the agent.

The evaluation, safety, and governance piece covers how to build governance practices that catch sandbox failures before they become incidents.

The operator's responsibilities

The agent is a tool. The operator is the accountable party. The agent's safety is the operator's design.

For a personal agent — one operator, one assistant, narrow scope — the minimum viable safety posture is: the agent works in a dedicated project directory, secrets live in the keychain, and external side effects require human review before firing. A personal agent that follows those three rules has a small blast radius even when it fails.

For a team agent — multiple operators, shared assistant, moderate scope — the minimum viable posture adds: a designated owner responsible for the agent's configuration, a change-log for operating instruction changes, and a shared understanding of what the agent is allowed to do without review. The practical applications piece covers the team generation in depth.

For a business agent — multiple agents, large user base, high blast radius — the minimum viable posture adds: formal governance review before deployment, observability on every agent action, an audit log that survives the session, and a legal review of the agent's external side effects. Business agent safety is a governance problem before it is a technical problem.

The agent eval workflow piece covers how to test whether the sandbox holds — including adversarial testing where the operator deliberately provokes the agent into doing things it should not do.

What this is not

This piece is not a guarantee that following the five practices prevents all failures. Each practice has edge cases, interaction effects, and implementation gaps that emerge in production. The practices reduce the probability and severity of failures; they do not eliminate them.

This piece is not a guide to containerization or VM-level sandboxing. Those are valid technical controls that sit below the agent layer. This piece is about the operational practices the operator controls directly, regardless of what isolation the runtime provides.

This piece is not a substitute for a security review. An agent that calls external APIs, handles credentials, or processes user input has a real attack surface. A security review — ideally by someone who is not the operator — catches gaps that the operator's mental model will miss.

See also