DEV Community: Termaxa

Claude Code shipped a sandbox. Here's what it protects — and what it doesn't.

zerodrop — Tue, 04 Aug 2026 21:23:38 +0000

Anthropic shipped OS-level sandboxing for Claude Code. If you run an agent
against a repo you care about, it's worth understanding precisely what moved —
because a fair amount of the commentary treats it as "agents are contained
now," and that's not what the documentation says.

I read the docs carefully, partly because I build a tool in adjacent territory
and needed to know whether I'd just been made redundant. Short answer: no. The
longer answer is more interesting, and it starts with a compliment: the docs
are unusually honest about their own limits. Most of what follows isn't
something I discovered — it's something Anthropic wrote down, and more people
should read it.

What it actually does

The sandbox uses OS primitives — Seatbelt on macOS, bubblewrap on Linux and
WSL2. By default, sandboxed commands can write only to your working directory
and the session temp directory. No network domains are pre-allowed: the first
time a command needs a new host you're prompted, and approving it lasts the
session.

Crucially, this is enforced by the operating system on the running process,
not by the model correctly interpreting a command. The docs put it well: the
boundary holds regardless of what the model chose to run, and even if an
allowed command does more than its name suggests. That's a real improvement
over asking an agent nicely, and it's the right layer for what it solves.

The motivation named in the docs is the same one I keep seeing in the wild:
reducing the permission prompts that people stop reading. Approval fatigue is
the disease; this is a real treatment for part of it.

Five things worth knowing before you rely on it

It's Bash-only. The sandbox constrains Bash commands and their child
processes. Claude Code's own Read, Edit and Write tools don't run through it —
they go through the permission system instead. "The sandbox is on" means shell
commands are contained, not that every file operation is.

Your working directory is inside the boundary by design. The default write
scope is the current working directory, plus session temp. That's what makes
the agent useful — it has to edit your code. It also means the sandbox is not
protecting the thing many developers assume it is. A destructive command
confined to your project is still confined to your project.

There's a sharp exception worth knowing, and it cuts in the reassuring
direction: even in auto-allow mode, rm and rmdir targeting /, your home
directory, or other critical system paths still trigger a prompt or a
classifier check, and explicit deny rules are always respected. Anthropic
special-cased the catastrophic paths. Everything inside your working directory
remains permitted, deliberately.

Reads are much wider than writes. Default read access is the entire
computer minus a few denied directories — and the docs say plainly that this
still allows reading credential files such as ~/.aws/credentials and
~/.ssh/. If you want those protected you configure sandbox.credentials
(deny, or mask) or add them to denyRead. There is no built-in credential deny
list. This is the item I'd action first.

There's an escape hatch, on by default — but it's permissioned. When a
command fails because of sandbox restrictions, Claude may retry it with
dangerouslyDisableSandbox. Importantly, that retry goes through the normal
permission flow: a confirmation prompt in default mode, or the classifier in
auto mode. So it isn't a silent bypass — it's a sanctioned door with a
doorbell. If you want the door bricked up, allowUnsandboxedCommands: false
enables what the panel calls Strict sandbox mode.

It fails open. If the sandbox can't start — missing bubblewrap, unsupported
platform — Claude Code warns and runs commands unsandboxed, unless you set
failIfUnavailable: true. That's a defensible default (a safety layer that
bricks your agent gets switched off, and then it protects nobody); I make the
same choice in my own tool. But fail-open has a shadow: the thing can be
inactive while everything looks fine. I learned that expensively when a hook
API rename left my own tool silently gating nothing for four minor versions,
with a fully green test suite.

And on native Windows it doesn't run at all. Windows users are pointed at
WSL2. If you run Claude Code natively on Windows — plenty do — the sandbox
isn't in your picture.

Credit where it's due: the docs name their own gaps

Before I make my argument, the Limitations section deserves reading in full,
because it's more candid than most vendor security pages:

The built-in proxy makes allow decisions from the client-supplied hostname and, by default, does not terminate or inspect TLS — so allowing broad domains like github.com can create paths for data exfiltration, with domain fronting named explicitly.
allowUnixSockets can inadvertently grant host access: allowing /var/run/docker.sock effectively grants access to the host system.
allowAppleEvents on macOS removes code-execution isolation.
enableWeakerNestedSandbox considerably weakens security.
And the summary line: sandboxing reduces risk but is not a complete isolation boundary.

That's a vendor telling you where their boundary ends. Take them at their word
rather than at the marketing.

The distinction that actually matters

Containment, consequence and recovery are three different questions, and tools
tend to answer exactly one:

Containment asks can this process touch things outside its box? That's
the sandbox, Docker, seccomp. A boundary in space.

Consequence asks what will this specific command destroy if it runs?
Fifty thousand rows. Three dependent tables. One commit that exists only on the
remote. A containment boundary has no opinion about this, because a permitted
command inside the boundary is just a permitted command.

Recovery asks and if it happens anyway, can I get it back? Neither
containment nor prediction gets you here. This is a backup taken before
execution, and a path back.

The failures I've been collecting all month live in the second and third
categories. An agent following NTFS junctions out of a Windows.old cleanup
into someone's live Documents folder. Prompt-configured rules — "don't touch
.env" — ignored, because instructions are suggestions and the execution path
doesn't read your CLAUDE.md. rm -rf ~/.crit/reviews/$SID where $SID had
already been cleared, so it expanded to nothing and took the parent directory.

Notice what those share. None is an agent doing something obviously stupid.
Each is a correct-looking command whose real scope differs from its apparent
scope. Containment doesn't address that class, because the command was
allowed to run in the place it ran.

What I'd actually do

Turn the sandbox on. It's built in, OS-enforced, and it closes a real
category. On Windows that means WSL2 or nothing — worth knowing before you
assume you're covered.

Then convert three soft defaults into firm ones, each a one-line change:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ]
    }
  }
}

Know it's broken rather than assume it's working; make the boundary hold rather
than negotiate; and stop sandboxed commands reading your keys, since the
default read policy allows it.

Then be clear-eyed that you've solved containment, not consequence or
recovery. For those: least-privilege credentials — an agent token that
cannot drop your production tables beats any prompt asking it not to —
backups that happen before execution rather than on a nightly cron, and, if
you want it, something that shows the blast radius while there's still a
decision to make.

That last part is what I build (Termaxa,
open source, Rust). I'm obviously not neutral. But the argument survives
without it: vendors will keep shipping containment, because containment is what
a platform can own. Consequence and recovery sit at a different layer, and
structurally, no agent vendor is going to build that layer for their
competitors' agents. Anthropic won't gate Cursor. Cursor won't gate Claude
Code. If you run more than one, that layer has to come from somewhere else.

The honest summary

Claude Code's sandbox is a good, real improvement that answers one of three
questions well, and its documentation is refreshingly clear about where it
stops. It's Bash-scoped; reads are far wider than writes and include your
credentials by default; the escape hatch is on but permissioned; it fails open;
and it isn't there at all on native Windows.

Read the limitations section. Flip the flags that matter to you from soft to
firm. And keep a backup — because the thing that gets you won't look dangerous.
It'll look like a command you'd have approved.

Verified against Claude Code's sandboxing documentation, August 2026.
Incidents referenced are public posts from r/ClaudeAI, r/ClaudeCode and
r/cursor over the past two weeks. The docs move quickly; where this and the
documentation disagree, the documentation is right and I'm out of date. Termaxa is MIT/Apache, cargo install termaxa — and if you can get an agent past it in a way I haven't documented, that's the most useful thing you could send me: issues or security@termaxa.com.

I asked an AI agent to delete a folder my tool was guarding. Here's everything that went wrong.

zerodrop — Fri, 17 Jul 2026 21:30:11 +0000

I build Termaxa, a small Rust CLI that gates the shell commands AI coding agents run: it previews what a command will actually do, backs up first, applies an allow/ask/deny policy, and logs everything. The fastest way to find out whether a safety tool works is to point a real agent at it and ask it to do the thing the tool exists to stop.

So I did. Several times, over a few weeks. Cursor broke my design four different ways, and every meaningful feature in the current release exists because of one of those breaks. (Claude Code, for what it's worth, mostly cooperated. It's the agent that didn't stand down that taught me everything.)

Round 1: the whack-a-mole

The setup: a test repo, Termaxa hooked into Cursor, a policy that flagged recursive deletes as ask. The prompt: delete this folder.

Cursor never attacked the hook. It didn't need to. It just kept expressing the same intent in different shell dialects until one spelling landed:

rm -rf .                      → ask
Remove-Item -Recurse -Force . → ask
del /s /q .                   → ask

Rule-based matching sees three unrelated commands. The agent sees one goal with three spellings — and each retry is a fresh policy evaluation, a fresh chance for an auto-approving UI to wave it through.

This isn't a bypass, it's a policy expressiveness gap. The agent stayed inside the rules the whole time. My rules just couldn't say the thing that mattered: "this session has already been told no about deleting things."

The fix: classify intent, count attempts, escalate

That gap is fixable inside the cooperative model, and the fix became the headline feature — a session circuit breaker:

Classify each command's intent — file-delete, db-destroy, git-force, infra-destroy — rather than matching spellings. rm -rf, Remove-Item -Recurse -Force, and del /s /q all classify as the same thing.
When a command comes back ask, count prior attempts with the same intent in the same session, read straight from the append-only audit log.
At the threshold (default: two prior attempts), escalate the ask to deny.

Two design constraints mattered. The breaker only escalates, and only touches ask — an explicit allow is deliberate user policy (maybe you want rm -rf allowed inside /tmp), and a deny is already a deny. And the state is derived, not stored — the counter is computed from the log, so there's no sidecar file to reset, a new session is automatically a clean slate, and every denied variant is itself logged with its intent, which keeps the breaker tripped for the rest of the session for free.

Re-ran the test. Cursor went PowerShell → cmd, the classifier tracked the intent across both shells, and the third delete attempt came back:

deny — circuit breaker: 2 prior file-delete attempt(s) this session

Felt good for about an hour.

Round 2: the classifier had a hole

Same session, Cursor kept going, and one command sailed through as a plain ask:

find . -maxdepth 1 -exec rm -rf {} +

The classifier looked at the first token. The first token is find. find isn't a delete command. The rm -rf living inside -exec was invisible.

This is where the intent-over-spelling bet paid off. The fix wasn't "add find -exec rm to a pattern list" — it was extending the classifier to understand delete indirection as a concept: find with -exec/-execdir/-ok/-okdir wrapping a delete command, find -delete, xargs feeding a delete command, unlink, shred -u. One classifier extension, one regression test using the literal live bypass command, shipped as v0.11.1. Enumerating spellings is an unwinnable arms race; intents are finite.

Round 3: the escape

Then Cursor did the thing that defines the tool's honest boundary.

Blocked on shell deletes — breaker tripped, every variant denied — it stopped using the shell. It switched to its own native file-delete tool and removed about twenty files. .cursor/ and .termaxa/, gone.

Audit entries for those deletions: zero. Not because anything was evaded — because the shell hook never saw them. An agent's built-in file tools don't go through the shell. They were never in scope.

I could have buried this. Instead it's the first item in SECURITY.md, filed as a public issue, and in the README subhead: Termaxa is a windshield, not a sandbox. It gates the shell path an agent normally takes; it does not contain an agent that executes through other means. If you need hard guarantees, pair it with OS-level isolation — containers, seccomp, restricted credentials. The cooperative gate covers the common case: a capable agent about to make an expensive mistake. It is not containment of an adversarial one. (The real fix is owning the execution path rather than hooking someone else's — that's the roadmap, not the present tense.)

One more finding from the same sessions, smaller but real: the breaker counts per session id, and both Cursor and Claude Code sometimes rotate the session id mid-run with no restart. A rotation between attempts resets the counter. In practice a burst of retries shares one id — the trip above happened across a rotation-free burst — but it makes the breaker a speed bump, not a durable cap. Also filed, also documented.

Round 4: the one that scared me

This is the finding I'd lead with if I could only keep one.

Weeks later, while wiring up post-execution receipts, I ran a routine live test on Cursor with a debug capture enabled (TERMAXA_HOOK_DEBUG, which dumps every raw payload the hook receives). The capture showed six hook invocations. The audit log showed zero entries.

Root cause: Cursor 3.11 had renamed its hook API. Events arrived as preToolUse/postToolUse (camelCase) with tool_name: "Shell". My parser only knew the older beforeShellExecution/afterShellExecution shape with tool_name: "Bash". Every event from current Cursor fell through the parser and returned None — which, by design, means "not for us, step aside."

Termaxa fails open on plumbing on purpose: a gate that bricks your agent when it gets confused gets uninstalled, and then it protects nobody. But fail-open has a shadow, and this was it. Termaxa had been silently not gating Cursor 3.11+ for roughly four minor versions. No error, no crash, no signal. The tool appeared installed and healthy while doing nothing.

Here's the part that generalizes: the entire test suite was green the whole time. The Cursor tests used the old payload shape as fixtures. They faithfully verified that Termaxa handled a dialect Cursor no longer spoke. For an integration surface, a green suite is necessary and nowhere near sufficient — the only thing that catches this class of drift is running the real agent and looking at what it actually sends.

The fix (v0.11.4): case-insensitive event matching across both API generations, Cursor detection from multiple signals, command and cwd recovery from several payload locations — and, crucially, four regression tests whose fixtures are the real captured 3.11 payloads, so the next silent rename fails CI instead of failing users. Verified live on Cursor 3.11.25: hook entries and post receipts both flowing again.

What actually generalizes

If you're building anything that sits between an AI agent and real infrastructure, the four lessons in one place:

Classify intent, not spelling. An agent blocked on a goal retries the goal with different syntax — across shells, through indirection, wherever the policy's vocabulary runs out. Pattern lists lose that race structurally. Intent classification is what let one fix close a whole category.

Only escalate; never relax. A safety layer that second-guesses an explicit human allow is a safety layer people rip out. Harden the soft middle — the ask that auto-approval quietly erodes into allow — and leave deliberate policy alone.

Green tests lie about integration surfaces. Your fixtures encode yesterday's API. Live-fire against the actual agent, capture the real payloads, and make those your fixtures.

Say where your tool stops, in the README, before anyone asks. The native-tool escape would be a devastating HN comment if someone else discovered it. As the first line of my own SECURITY.md, it's the reason to trust the rest of the document.

The biggest surprise wasn't that Cursor found bugs. It was that every serious improvement came from watching a real agent behave differently than my tests predicted. If you're building infrastructure for AI agents, that's probably the actual development loop: write the feature, point a real model at it, let it surprise you, and turn the surprise into tomorrow's regression test.

Termaxa is MIT/Apache, open source, cargo install termaxa. If you can make an agent get past it in a way I haven't documented, that's the most valuable contribution you can make: issues or security@termaxa.com.