# bashkit tested: a bash sandbox for AI agents

Canonical: https://www.kartikaydhar.com/blog/bashkit-bash-sandbox-ai-agents
Published: 2026-11-17T02:48:52.48+00:00
Updated: 2026-11-17T02:42:38.530267+00:00
Category: Tool Breakdowns

I ran bashkit 0.21.0, a pretend bash and file system for AI agents. It blocked my files and the network, but rm -rf /* still wiped its own files.

bashkit is a free, open-source sandbox that gives an AI agent a bash tool without giving it your computer. Bash is the text command language programmers use to work with files on Linux and Mac. A sandbox is a walled-off space where commands can't reach anything real. bashkit, from the Everruns project, rewrites 167 bash commands in Rust, a programming language, and runs them on pretend files kept in memory. If your product lets an AI agent tidy data, write reports or run scripts for a customer, this gives the agent a terminal inside your own app, with no extra machine to run or pay for.

I ran it in Python. It kept my real folders, the internet and an endless loop out of reach, and each call took a millisecond or two at most. The catch is that it is a convincing fake, not a real computer. A command asking for administrator rights pretends to work. One version of the delete-everything command really does empty the sandbox. And after 1,000 calls in one session, it stops working.

## What I tested

- Version: bashkit 0.21.0 for Python, the latest release (published 11 November 2026).
- Setup: one command, pip install bashkit (pip is Python's installer), in a fresh environment. It took 1.2 to 1.8 seconds over three installs and needed no account or key.
- Task I ran: a small CSV file (a spreadsheet saved as plain text) of weather readings (city, date, temperature, rainfall), summarised with standard command-line tools inside the sandbox. Then a set of escape attempts: reading my real folders, reaching the internet, deleting everything, running a loop that never ends, and pretending to be an administrator.
- Time to first result: a new sandbox usually started in about 0.25 milliseconds; the first one in each run took up to 4.2 milliseconds. The first awk summary took 0.5 to 1 millisecond and the first jq count 1.1 to 1.4 milliseconds, with repeats at about 0.1 and 0.8 milliseconds. 1,000 calls took 26.7 to 27.3 milliseconds. A saved snapshot was 2,091 bytes and restored in about a millisecond.
- What worked: the summaries were correct, files and settings carried over between calls, and every attempt to reach my machine or the internet was refused.
- What broke or surprised me: rm -rf /* emptied the sandbox, sudo ran commands without complaint, and the 1,001st call in a session failed. The Rust library lets you change that call limit; I didn't find a setting for it in the Python package.

## What is bashkit, and why would an agent need it?

Many AI agents get a "bash tool": the ability to type commands, read files and run small programs, the way a developer would in a terminal. That also means an agent with a bad instruction, or a malicious web page in front of it, could delete files, read secrets or send data somewhere.

One common answer is a container or a separate virtual machine, a whole extra computer you have to run and pay for. bashkit takes a different route. It is a library, a block of code you add to your own program. When the agent sends a command, bashkit interprets it itself. No real program is started. The README says there is "no process spawning, no filesystem access, no network access unless explicitly enabled."

Image: Illustration: What is bashkit, and why would an agent need it?

How bashkit runs a command, based on its README and my run.

The files live in a virtual filesystem: folders and files that exist only in the program's memory and vanish when it closes. It is written in Rust, with Python and JavaScript versions, and it is MIT licensed, which means anyone can use it for free, including in paid products. The repo had 390 stars, GitHub's bookmarks and a rough sign of interest, when I checked on 17 November 2026. The README calls it "a free, open-source hobby project."

## Does ordinary command-line work actually function?

Yes, for what I tried. I put a seven-row weather CSV into the sandbox and asked for the average temperature and total rain per city. I used awk, a small language for pulling columns out of text, and sort to put the cities in order. The answer came back right: Pune averaged 25.0°C with 4 mm of rain, Delhi 17.5°C with none, Shimla 5.0°C with 32 mm.

Then I used jq, a tool for reshaping JSON (the text format most web services use for data), to count rainy days per city. Delhi had 0, Pune 2 and Shimla 2, which matches the file.

Each request your program sends to run some bash is one exec call. Each call took a millisecond or two at most, usually less, and 1,000 calls took about 27 milliseconds in total.

State carried over between calls. I set an environment variable, a named setting that commands can read, in one call (CITY=Shimla) and moved into the /data folder. The next call still saw both.

## What does it block, fake and still get wrong?

Image: Illustration: What does it block, fake and still get wrong?

What happened when I tried to break out, redrawn from my test output.

### Blocked

My real working folder didn't exist inside the sandbox: ls /workspace returned "No such file or directory." The sandbox has its own small set of folders, and its user list contains only the name I gave it and a placeholder.

curl and wget, the usual commands for fetching web pages, both failed with "network access not configured." You can switch the network on with an allowlist, a list of the only web addresses allowed. When I allowed one address, a different one was refused with "URL not in allowlist."

A loop written to run forever stopped in about 1.2 milliseconds with "maximum command count exceeded (500)." That 500 was a limit I set. The default is 10,000 commands per call.

Commands that need a real computer fail with clear messages. apt-get and docker each said they aren't available in the sandbox. python3 was "command not found" by default; Python is an experimental extra you can switch on, and when I did, python3 worked. ssh said it needs an extra "ssh" feature.

### Faked

Some commands return believable answers rather than errors. ps aux, which lists running programs, showed one pretend bash process. whoami and hostname returned the user and machine names I chose.

sudo, the command for running something as an administrator, didn't refuse. sudo ls listed the folder, and sudo -u root id reported the ordinary user, not root. Nothing was gained, because there is no administrator to become, but an agent reading that output could easily think its sudo worked.

### Still surprising

rm -rf /, the classic "delete everything" command, finished with a success code and deleted nothing. rm -rf /*, a small variation, did delete things: a test file I had saved, the home folder and the temporary folder were gone. Your real disk is safe either way, but anything the agent saved in the sandbox is not.

After 1,000 exec calls, the 1,001st call failed with "session exec() call limit exceeded (1000 calls)." The cap counts calls, not commands: one call can run up to 10,000 commands. In practice, a long agent session that sends one call per step would hit it after 1,000 steps. The source code sets this default on purpose, so a user can't get around the per-call limits by splitting work across many calls.

Saving and restoring the sandbox doesn't clear the cap. A snapshot, a saved copy of the sandbox's files, settings and current folder, carries the call count with it, so a sandbox restored from a capped session failed too. Only reset(), which wipes the sandbox back to how it started, cleared the cap, and it erased every file along with it.

bashkit also has analyze(), which reads a command without running it so your app can decide whether to ask a person first. I gave it a command that uploads a file with curl -d @/data/weather.csv and then deletes the folder. It listed curl and rm and showed every argument, including the file name, but it didn't single out the file being sent. The docs say analysis is "advisory, not a boundary." The network allowlist is what actually stops the upload.

## What this means for product and GTM teams

For a product where an AI agent works with files, bashkit is a low-cost way to give it a terminal. It is free, it installs in seconds, and it runs inside your own app.

The trade-off is that the agent works in a convincing copy of a computer. Most of the time that is the point. But a few behaviours are fakes that look like success (sudo, ps), one delete command still works, and long sessions hit a hard stop at 1,000 calls. Whoever builds the product needs to plan for those: save the files the agent produces outside the sandbox, start a new session before the cap, and keep the network allowlist as small as possible.

bashkit is a different kind of sandbox from the one I covered in my post on NVIDIA OpenShell, which applies policy rules at the operating-system level to real programs. For how a bash tool fits into the wider loop around an agent, see harness engineering and my test of the shim harness.

## How do I try it?

This is a short job for an engineer who knows Python, and a good first test is running one of your agent's real tasks inside it. Install it:

pip install bashkit

Run a command:

from bashkit import Bash

bash = Bash()
r = bash.execute_sync("ls /")
print(r.stdout)

Success looks like a short list of folders such as bin, etc, home and tmp, none of them yours. To let the agent reach one website, pass an allowlist:

bash = Bash(network={
  "allow": ["https://api.github.com"]
})

For an AI tool, the package includes BashTool, which comes with ready-made instructions that tell a model how to use the sandbox. They list the command limits and say Python isn't available, but they don't mention the 1,000-call cap, so add it to your agent's instructions yourself.

## Frequently asked questions

### What happens to the agent's files when the session ends?

They live only in memory. A second sandbox I started couldn't see files the first one had saved, and reset() erased them. To keep a file, your app has to read it out first, which worked in my test, or connect a real folder.

### Can the agent read or change my real files?

Not by default. You can connect a real folder, and I tried both kinds. In a read-only folder, writing and deleting were refused with "realfs is mounted readonly". In a writable one, a file the sandbox created appeared on my real disk, and bashkit printed a warning that scripts can modify host files.

### Is it safe against a malicious web page?

bashkit limits what commands can reach, not what an agent is told to do. analyze() shows what a command will run, but the project's docs call it advisory, not a boundary. The real guard against data leaving is the network allowlist, and with no allowlist set, curl and wget fail.

### Can it run Python or Node.js?

Not by default. The README lists Python, TypeScript and SQLite as experimental options you switch on. With Python switched on, my python3 test worked.

## Sources

- everruns/bashkit on GitHub (README, checked 17 November 2026)
- bashkit releases (v0.21.0, 11 November 2026)
- bashkit on PyPI
- bashkit Python package README (mounts)
- bashkit script analysis guide
- bashkit threat model
- bashkit limits source (session limit defaults)
