Sandboxes

An AI agent offers tools to a model: read a file, write a file, run a command. The model picks a tool and the tool does real work. One detail is often overlooked: the work has to happen on some particular computer.

For agent software installed on your own computer, the answer is your computer. The tool reads your real files and can delete your real files. If the model asks for the wrong action, the wrong action happens to your data.

A sandbox is a boundary placed around the agent. Inside the boundary the agent can work. Outside it, the agent cannot read or change anything. This lesson explains where tools run, what an unrestricted agent can reach, how permissions and sandboxes narrow that reach, and what a sandbox does not guarantee.

After this lesson you can say what a sandbox protects, what it leaves at risk, and what to check when a product says it is sandboxed.

1. The model asks, your machine runs

Two parties are involved in every tool use, and they do different jobs.

A tool call is a short piece of text in which the model names a tool and the details for it, for example "write the file summary.md with this content". The model produces that text and nothing else. It cannot touch a disk.

The agent software receives the tool call and executes it, which means it carries out the action for real. Then it sends the result back to the model, and the model continues. The lesson on the agent loop describes this cycle.

sequenceDiagram
    participant M as Model (at the provider)
    participant A as Agent software (on your machine)
    participant D as Your disk
    M->>A: Tool call: write summary.md
    A->>D: Writes the file
    D-->>A: Done
    A-->>M: Result: file written

The model usually runs on the provider's computers, far away. The agent software runs wherever it is installed. So an action is asked for in one place and carried out in another. The place where it is carried out is the place whose files are affected.

2. The file is written to your real disk

Take a concrete case. You install an agent application, for example Claude, on your computer. You ask it to summarise the documents in a project folder.

~/                      your home folder, on your real disk
    projects/acme/      where you asked it to do the work
        summary.md      written by the agent

The symbol ~/ is a common short way to write the home folder, the folder that holds one user's personal files.

After the agent finishes, summary.md is a real file in ~/projects/acme/. It was not created in some separate practice area. It sits on your disk next to your other files, and it stays there after you close the application.

This is the purpose of a local agent: it does real work on your real files. The same fact is the source of the risk. Software that can create a real file can also overwrite or delete one.

3. What an unrestricted agent can reach

The agent software runs under your user account, so it has your permissions. Permissions are the rules of the operating system about what an account may read, change, and delete. Whatever you can open, the agent can open. Whatever you can delete, the agent can delete.

Suppose your computer has these six areas:

flowchart LR
    AG["The agent<br/>with your permissions"]
    subgraph R["Everything the agent can reach"]
        direction TB
        D1["Documents"]
        D2["Projects"]
        D3["Photos (read)"]
        D4["Downloads (deleted)"]
        D5["Backups"]
        D6["Settings"]
    end
    AG --> R

With broad access, all six areas are inside the agent's reach. The diagram marks two events that nobody asked for. The agent read the Photos folder, and it deleted the Downloads folder. You asked for work in one project, but nothing stopped the agent from going elsewhere.

There are three common reasons for an agent to do something like this:

• A misunderstanding. You write "clean up the old files", and the model picks a wider set of files than you meant.
• A mistake by the model. The model writes a delete command with the wrong folder path.
• Hidden instructions. A document or web page the agent reads contains text that tells it to do something harmful. This attack is covered in a later lesson on prompt injection.

In none of these cases does the agent need bad intent. Wide reach plus one wrong tool call is enough.

4. First answer: you grant access folder by folder

At the time of writing, the widely used agent applications that work on your own files, such as Claude, ChatGPT, and many others, come with the same basic answer to this problem. The agent starts with access to none of your folders, and you grant access one folder at a time.

Before the agent touches a folder, it asks:

Grant access to ~/projects/acme

    [ Allow this folder ]
    [ Deny everything else ]

Nothing is opened until you answer. After you have allowed two folders, the list of what the agent may touch looks like this:

This list was written by you, one folder at a time. The agent's reach is now the two folders you named, not the whole disk.

The exact dialogs and settings differ between products and change over time, so check the documentation of the agent you use.

5. The sandbox: the same machine with a boundary

A sandbox turns that idea into an enforced boundary. The name comes from a children's sandbox: a box in which a child can dig and build freely while the sand stays in the box.

Here is the same computer as before, with a sandbox:

flowchart LR
    subgraph SB["The sandbox: everything in here is at risk"]
        direction TB
        AG["The agent<br/>with your permissions"]
        D1["Documents"]
        D4["Downloads"]
        AG --> D1
        AG --> D4
    end
    subgraph OUT["Outside: nothing out here is at risk"]
        direction TB
        D2["Projects"]
        D3["Photos"]
        D5["Backups"]
        D6["Settings"]
    end
    SB -. "blocked" .-> OUT

In this picture the sandbox contains the agent and two areas, Documents and Downloads. The agent can read and change those. The other four areas, Projects, Photos, Backups, and Settings, are outside. The agent's attempts to reach them are blocked.

The diagram has two labels, and both are needed to describe a sandbox correctly:

• Everything inside is at risk. The sandbox does not protect what is inside it. If the agent deletes the Downloads folder in this setup, the folder is gone.
• Nothing outside is at risk, as long as the boundary holds.

A sandbox can limit more than folders. Depending on the product, it can also limit which programs the agent may run and whether it may use the network. The principle is the same: the agent gets a small, defined area instead of the whole system.

The important difference from a plain instruction is who enforces the limit. Telling the model "please stay in this folder" in a prompt is a request that the model may fail to follow. A sandbox is enforced by software outside the model, usually the operating system. A blocked action fails no matter what the model asked for.

6. A sandbox limits the damage, it does not make the agent safe

A sandbox does not change how the agent behaves. The model can still misunderstand a request or issue a wrong command. What changes is how far the consequences can spread.

So the accurate description is: a sandbox does not make the agent safe. It makes the possible damage small. Ideally, a mistake stays inside the folders you named.

An analogy: a fire door does not prevent a fire. It keeps a fire in one room so that the rest of the building is not lost. The agent's mistake is the fire, the sandbox is the fire door, and the folders inside the sandbox are the room. The analogy stops being accurate at one point: a fire door is passive, while a sandbox is software that can contain errors of its own.

This gives a practical criterion for setting one up. Put inside the boundary only what the task needs, and only what you could afford to lose or can restore from a copy.

7. Sandboxes have been escaped

The previous section said "ideally" for a reason. A sandbox is software, and software can have flaws.

Getting past the boundary is called a sandbox escape. Escapes are known from many kinds of sandboxes, not only those around AI agents.

The consequence is that a sandbox is one layer of protection and not a guarantee. For this reason it is usually combined with other layers: narrow permissions, backups of important data, and a person who approves risky actions.

8. What to know when a product says "sandboxed"

There is no single sandbox technology. Underneath the word there are several different technical implementations. Some use features of the operating system that restrict one program. Some run the agent in a container or a virtual machine, which are ways of running software in an isolated environment that behaves like a separate computer. Some run the agent on a remote machine in a data centre, so that it never touches your computer at all.

For someone who uses an agent, the two rows below separate what can be skipped from what needs to be known:

When a product says it is sandboxed, the useful questions are about coverage: which folders are inside, whether the network is reachable, and what the agent can do without asking.

9. For people who build agents

The picture changes if you are the person writing the agent software.

1. A tool call arrives. It was requested by the model. You did not write it, and you cannot know in advance what it will contain.
2. Your code decides where it runs. The model has no say in this, and nothing else in the system decides it for you.
3. Inside a boundary, or not. That decision is the whole sandbox question.

A boundary does not appear by default. It is something the builder puts in or leaves out. If the code runs every tool call directly on the host machine with full permissions, then the agent has no sandbox, whatever the model was told in its instructions. The harness, the software around the model, is where this decision is made.

Interview points

• The model never executes a tool. It returns a tool call, and the agent software executes it on the machine where that software is installed.
• A locally installed agent writes real files to the real disk and runs with the permissions of the user who started it.
• With broad access, an agent can read, change, or delete anything the user can, so one wrong tool call can affect unrelated data.
• Mainstream agent applications start with no access and ask the user to grant it folder by folder. Everything not granted stays out of reach.
• A sandbox is an enforced boundary around the agent. Resources inside it are still at risk, and resources outside it are protected while the boundary holds.
• A sandbox is enforced by software outside the model, so it works even when the model does not follow its instructions.
• A sandbox does not make an agent behave correctly. It limits how much damage a mistake can cause.
• Sandbox implementations have had vulnerabilities, and agents have escaped through them. A sandbox is one layer of defence and should be combined with others.
• Sandboxes are implemented in several ways, including operating system restrictions, containers, virtual machines, and remote machines. For a user, the coverage of the boundary matters more than the implementation.
• When building an agent, the builder's code decides where each tool call runs. A sandbox exists only if the builder adds one.

Summary

• The model asks for actions, and the machine with the agent software carries them out.
• A local agent works on real files with the user's permissions.
• Without limits, the agent can reach everything the user can reach.
• Folder-by-folder permissions reduce that reach to a list the user wrote.
• A sandbox is a boundary: what is inside is at risk, and what is outside is not.
• A sandbox makes the damage of a mistake smaller. It does not prevent the mistake.
• Sandboxes can have flaws and have been escaped.
• For a product, check that a boundary exists and what it covers.
• For a builder, a boundary has to be built in on purpose.