To sandbox an AI terminal assistant, run it where it can see only the project it is working on: a container or separate OS user, no inherited cloud or Git credentials, a restricted network, and a disposable copy of the code. Then approve anything outside that boundary by hand.
Why sandbox at all
A terminal assistant acts with the permissions of whoever launched it. If you start it in a normal shell, it can read your home directory, your SSH keys, your shell history, and any logged in command line tools. The MCP project's security guidance makes the same point about local tool servers: they run with the same privileges as the client, and it recommends running them in a sandbox with minimal default privileges and explicit grants for extra access.
A sandbox does not make the model smarter. It makes mistakes smaller.
Six steps
- Work on a copy. Clone the repository into a fresh directory, or use a separate worktree. Never point the assistant at a directory that holds other projects.
- Use a container or separate user. A container image with the language toolchain and nothing else is a good default. Mount only the project directory. If containers are not an option, create a dedicated OS user with no access to your home directory.
- Strip ambient credentials. Do not mount your SSH agent socket, cloud config folders, or package registry tokens. If the task needs a token, issue a narrow one for that repository and let it expire.
- Limit the network. Allow the model endpoint and your package mirror. Block everything else, and add hosts by request. This also makes data exfiltration noisy instead of silent.
- Keep approvals on for risky actions. Package installs, new network destinations, edits to pipeline files, and deletions should prompt a person even inside the sandbox.
- Review and merge from outside. Pull the changes out as a diff, review them on your normal machine, and push from there. The assistant never holds push rights to a protected branch.
What a sandbox does not cover
| Threat | Sandbox helps? | What else you need |
|---|---|---|
| Reading your SSH keys | Yes | Nothing more if keys are not mounted |
| Running a hostile install script | Partly | Network limits, package review |
| A bad change in the code itself | No | Code review, tests, policy gates |
| A poisoned instruction in a file | No | Treat repository text as untrusted input, review diffs |
| The model endpoint seeing your code | No | Vendor data terms, scope what you send |
The last three rows are why a sandbox is one layer and not the whole answer.
Make it easy so people use it
Developers skip controls that cost them minutes. Publish a small wrapper script or dev container definition that starts the assistant inside the boundary in one command. Put it in the repository template. Document how to request a new host or mount. If the safe path is the fast path, adoption follows.
Check it works
Test the boundary before you trust it. Inside the sandbox, ask the assistant to print environment variables, list your home directory, and fetch a page from a blocked host. All three should fail or show nothing sensitive. Repeat after each tooling upgrade, because updates can change defaults.
For deeper reading on egress limits, see our post on agent runtime egress controls.
A worked example: a container for a Python project
Here is what the six steps look like for a small service. The team builds one container image with the Python version, the test runner, and the linter. It contains no cloud command line tools, no SSH client configuration, and no registry credentials.
| Setting | Value | Reason |
|---|---|---|
| Mount | The project directory, read write | The agent needs to edit and test |
| Other mounts | None | Nothing else should be visible |
| User | Non root, no sudo | Limits damage from a hostile command |
| Environment variables | Only those the tests need | No inherited tokens |
| Network | Model endpoint and package mirror | Everything else blocked |
| Time limit | Session ends after a set period | Forces a fresh start |
A developer starts the session with a single wrapper command. Inside, the agent edits files and runs tests. When it asks to install a new package, the request is routed to a person, because installs are in the always prompt tier. When the session ends, the developer reviews the diff outside the container and pushes from their own machine.
Now imagine a hostile instruction in a dependency's documentation telling the agent to read the home directory and send it somewhere. Inside the sandbox, the home directory holds nothing of value, and the network rule blocks the destination. The attempt shows up as a blocked request in the log, which is exactly what you want to see.
Choosing the boundary
| Approach | Strength | Weakness |
|---|---|---|
| Separate OS user | Easy to set up | Shares the kernel and network with the host |
| Container | Good file and process isolation | Needs network rules and care with mounts |
| Virtual machine | Strong isolation | Heavier to run and maintain |
| Remote development environment | Central control and logging | Needs infrastructure and cost planning |
Pick the lightest option that matches the sensitivity of the code. A throwaway virtual machine suits the riskiest tasks. A container suits daily work.
Maintaining the sandbox
- Keep the image small and rebuild it on a schedule so it picks up patches.
- Pin the toolchain versions so runs are reproducible.
- Review the allowed host list quarterly and remove entries nobody uses.
- Record each exception to the boundary with an owner and a date.
- Re-run the boundary test after each upgrade of the assistant itself.
Failure modes to watch
- A developer mounts the home directory "just this once" and leaves it that way.
- The network rule allows a wide domain that hosts user content, which makes exfiltration easy.
- A cached credential sits inside the image because someone built it on a logged in machine.
- The wrapper script drifts from the documented version and people copy old copies.
Each of these is a process problem, so treat the wrapper and image as maintained software with an owner.
Try it yourself
Click through it at your own pace, or open it full screen.
Click through and notice what runs on your own machine and what is sent onward.
Safeguard can help at the dependency and pipeline end of this: SBOM and dependency scanning, reachability analysis, policies and gates on pull requests, and agent identity. The Safeguard CLI can also write code, and the download page lists a Local agent and a Cloud agent as available. You can try a free scan at gold.safeguard.sh/scan.
Quick check
Is a container enough?
It is a strong start, but a container with your credentials mounted is not a sandbox. The credentials and network rules matter as much as the isolation.
Do we need this for a small task?
If the assistant can run commands, yes. The setup cost is paid once in a template.
Does a sandbox slow developers down?
A wrapper that starts it in one command adds seconds, not minutes. The slowdown people feel is usually from missing tools in the image, so build it with the project's real toolchain.
Sources
Last reviewed: 19 October 2026.
