The report checked out, and the fix is already available in v1.16.0.

Update to v1.16.0

If you use ai-jail, the update is the usual drill:

# Arch Linux (AUR)
yay -Syu ai-jail-bin

# Homebrew (macOS / Linux)
brew update && brew upgrade ai-jail

# crates.io
cargo install ai-jail --force

# mise
mise cache clear && mise upgrade github:akitaonrails/ai-jail

What changed in v1.16.0

Up through v1.15.x, ai-jail mounted the Docker socket inside the jail automatically whenever /var/run/docker.sock existed on the host. Read-write. No warning, no flag, no asking for your opinion. I documented this in the README as “favors usability,” and it was true: a coding agent often needs to run docker compose to bring up a test database, and the automatic passthrough saved some configuration.

Starting with v1.16.0, the behavior flipped:

• Socket passthrough is now off by default. It only goes in if you explicitly ask for it with the --docker flag or no_docker = false in .ai-jail.
• When you enable it and a host socket exists, ai-jail prints a launch warning spelling out that this amounts to giving host root to the process inside the jail.
• ai-jail status now shows Docker as disabled (default), so nobody thinks it got turned on by accident.
• In --lockdown and browser profile modes the socket never goes in, same as before.

A behavior change, yes, and a deliberate one. If your workflow depends on Docker inside the jail (mine does, in a few projects), opting in is one line in the project’s .ai-jail:

no_docker = false

The field name is ugly (no_docker = false to turn it on, I know), but old configs keep parsing the same way, and --no-docker / no_docker = true work as before. Only the default changed. The details are in the v1.16.0 release notes.

What issue #88 showed

mdindoffer’s report is the kind every maintainer wants to get: precise summary, a repro in a few lines, a fix proposal. The gist:

ai-jail was mounting the raw Docker socket inside the sandbox, read-write. The Docker daemon runs as root on the host. So an agent inside the jail could run this:

docker run --rm -v /:/host alpine sh -c 'cat /host/etc/shadow'

And that’s the ballgame. Read any file on the host, as root. It defeats the tmpfs $HOME, --mask, --deny-path, and Landlock in one move, because the action no longer happens inside the sandbox: it happens in the daemon, which lives outside and above any namespace bwrap created. The agent doesn’t even need to escape the jail when the jail has a door straight into the engine room.

In retrospect, shipping this on by default was a design mistake. I knew the passthrough was “dangerous” in the abstract, and I wrote as much in the README. What I hadn’t internalized: dangerous like this, with this default, is a vulnerability.

mdindoffer also proposed the definitive hardening path: instead of mounting the raw socket, put a filtered proxy in front of it (in the style of wollomatic/socket-proxy) that only accepts bind mounts from paths the agent can already write to inside the jail. It’s on the radar for a future release. To close the hole now, opt-in with an explicit warning fixes the default, which is where the problem lived.

The vulnerability class: docker.sock is root

This is not the first time I’ve run into this story, and I’d bet it isn’t yours either. “Whoever has access to the Docker socket has root on the host” is one of the classics of container security, documented by Docker itself on the daemon attack surface page: only trusted users should control the daemon, because Docker lets you share any host directory with a container, with no access restriction whatsoever.

The technical reason is simple. dockerd is a daemon that runs as root and obeys commands arriving through the API on the /var/run/docker.sock Unix socket. The docker CLI is just a client of that API. When you ask for docker run -v /:/host, the daemon is the one creating the container and mounting the host’s entire filesystem inside it, with full privilege. And a process inside a container runs as uid 0 by default, which the kernel sees as real uid 0 (barring user namespace remapping, which almost nobody turns on). The math checks out: write access to the socket equals root on the host. The docker group is passwordless sudo by another name.

The demo, on your machine

If you have Docker installed and your user in the docker group, reproduce it right now. No sudo, no exploiting any bug:

# confirm you're a regular user
$ id
uid=1000(akitaonrails) gid=1000(akitaonrails) groups=...,docker

# try reading /etc/shadow directly: denied, as expected
$ cat /etc/shadow
cat: /etc/shadow: Permission denied

# now ask the daemon to do it for you
$ docker run --rm -v /:/host alpine sh -c 'head -3 /host/etc/shadow'
root:$6$...:...
bin:!:...
daemon:!:...

And if you want the whole nine yards, a root shell on your own host:

$ docker run --rm -it -v /:/host alpine chroot /host /bin/bash
# id
uid=0(root) gid=0(root) groups=0(root)

No exploit, no 0-day. You used the official API, the documented way, and went from regular user to root in one command. That’s exactly what an agent inside ai-jail could do until today, even with every layer (bwrap, Landlock, seccomp, rlimits) turned on.

Why does this still exist?

If everyone has known about this for over a decade, why hasn’t anyone “fixed” it? Short answer: this is architecture, and architecture doesn’t get patched.

• The root daemon with an all-powerful API was the design that made Docker simple to operate. Granular per-request authorization exists in the form of authorization plugins, but it’s opt-in, annoying to configure, and I can count on one hand the setups I’ve seen using it.
• userns-remap has been around since Docker 1.10 and maps container root to an unprivileged user on the host. It ships turned off, because it breaks compatibility with images and volumes that assume uid 0.
• Rootless mode runs the whole daemon as your user, with the socket at $XDG_RUNTIME_DIR/docker.sock. It works, but it has network and storage limitations, and the entire internet of tutorials assumes the root daemon at the classic path.
• Podman was born rootless and daemonless precisely because of this criticism. There’s a whole section about it below.

Bottom line: this is here to stay. Every tool that mounts /var/run/docker.sock into an environment “for convenience” opens the same hole, knowingly or not. CI mounting the socket for image builds, remote IDEs, code-server, AI agent sandboxes (hi, me), web dashboard plugins. The fix always lives on the side of whoever builds the environment.

Fun fact: this is anything but new

If you’ve been following me for a while, this whole story should give you déjà vu. Back in 2023 I recorded [Akitando #139] - Understanding How Containers Work, where I explain what a container actually is: an ordinary Linux process, throttled by cgroups, fooled by namespaces, with its capabilities trimmed. No magic and no virtual machine. And look at what was already sitting in that episode’s link list: a walkthrough of privilege escalation via Docker, demonstrating the exact docker run -v /:/host trick. The hole issue #88 exploited inside ai-jail is the same one I was already pointing at in a 2023 video, and it was old news long before that.

Nobody knows this better than Red Hat. Podman was born there in 2018 as a direct answer to that architecture: no central daemon, rootless by default. Every container becomes a direct child of your user, via fork-exec, with no all-powerful process running as root brokering anything. The whole “docker.sock is root” problem doesn’t exist in that model, because there’s no docker.sock, no daemon, and no root.

And before you ask: yes, I run Podman for some things and I recommend it. But it’s no perfect solution either, and it’s worth understanding why.

What Podman does well:

• The right architecture. Daemonless and rootless from day zero. The entire vulnerability class from this article stops making sense.
• CLI compatibility. alias docker=podman covers the overwhelming majority of day-to-day commands. Build, run, push, pull: same commands, same flags.
• systemd integration. Quadlets are, in my opinion, the cleanest way to run a container as a service on Linux. Docker never came close.

Where it stumbles:

• The compatibility socket isn’t 100%. Podman offers a socket compatible with the Docker API (podman.socket), and plenty of tools work on top of it. But “plenty” isn’t “all”: Testcontainers, some IDE plugins, more exotic CI tooling trip over behavioral differences. It works until the day it doesn’t, and then you lose an afternoon debugging.
• Compose is a second-class citizen. The official docker compose does talk to the Podman socket, and podman-compose exists, but neither has the polish of the original pairing. Projects with a complicated compose file are where migrations usually get stuck.
• Rootless has a price. Rootless networking (slirp4netns, and pasta these days) has limits: no ping by default, weird source IPs, lower throughput. Images that assume uid 0 and volumes with wrong permissions need fiddling. Nothing fatal, but it’s friction.
• Docker Desktop is a product. On macOS and Windows, Docker Desktop delivers a polished experience that Podman Desktop is still catching up to. For a lot of people, that’s the only contact with containers they’ll ever have.

Add it all up and you get the answer to why the world stays on Docker: ecosystem inertia. Every tutorial, every CI pipeline, every example image, every docker run pasted from Stack Overflow assumes the root daemon at the classic path. Docker became the name of the category, the Kleenex of containers. Moving to Podman is technically easy and politically expensive: it’s you against the accumulated knowledge of the entire internet.

One detail that matters for sandbox users: mounting the rootless Podman socket inside a jail is far less catastrophic than mounting the Docker one. The equivalent “daemon” runs as your user, so a malicious agent would gain your privileges, not root. Still bad (it could overwrite your ~/.ssh, for one), but a whole different ballgame. Even so, ai-jail’s default stands: don’t mount any socket, from any runtime. Opt-in is opt-in.

Best practices so this doesn’t bite you

The list I apply and recommend:

1. Treat the docker group as passwordless sudo. Before adding any user or service to it, ask whether you’d give that thing unrestricted sudo. Same thing.
2. Never mount /var/run/docker.sock into untrusted environments. AI agents, CI jobs running code from a stranger’s pull request, third-party containers. Run grep -r docker.sock over your docker-compose files, CI manifests, and tool configs. It shows up in more places than you remember.
3. Need to expose it to something semi-trusted? Use a socket proxy. wollomatic/socket-proxy and Tecnativa’s docker-socket-proxy sit between the client and the daemon with an endpoint allowlist and blocking of arbitrary bind mounts. Read-only by default; you enable only what you need.
4. Prefer rootless whenever possible. Rootless Podman on Linux is the cleanest path; Docker’s own rootless mode is the second option. The daemon stops being root and this entire class of problem loses its bite.
5. In CI, build images without a privileged daemon. Kaniko and Buildah build images rootless, with no socket mounted in the job at all.
6. Can’t go rootless? Turn on userns-remap. It costs an afternoon of testing with your volumes and buys real isolation between container root and host root.
7. In ai-jail, let the default work for you. Docker off, and --docker only in projects where you trust the workload the way you’d trust a sudo. Rule of thumb: if you wouldn’t blindly hand sudo to the agent in that directory, don’t hand it --docker either.

Conclusion

A well-built sandbox loses much of its value with a back door left open for convenience. bwrap, Landlock, seccomp, and rlimits in ai-jail keep doing their jobs, but none of them can see what happens when the process inside politely asks the host’s root daemon to mount the whole filesystem into a container. A security layer you don’t audit becomes decoration.

My public thanks to @mdindoffer: clean report, minimal repro, correct severity, and a solution proposal on top. That’s how you report a vulnerability to an open source project.

If you want the full context of how I use sandboxes day to day, I wrote about it in How Do I Protect Myself From My Agents Deleting My Stuff?. The ai-jail story is in AI Agents: Locking Down Your System and in the Rust rewrite.

Now go run the upgrade.

Version 1.1.0 shipped that same day. Today, July 20, we’re at 1.17.1.

Version numbers alone don’t mean much, so I counted what actually happened after that post went live: 31 releases, 55 merged pull requests, and 46 closed issues. I counted 24 groups of new user-facing features in the CHANGELOG, ignoring fixes, documentation, and internal details from the same delivery. If I split the new ai-memory run family into auto-selection, session adoption, Crush support, --yolo, search, and recovery, we’d blow past that number.

Fifteen people had PRs merged during that period, fourteen besides me. Special thanks go to Djalma Júnior, who alone had 24 PRs merged, Matheus Rodrigues, with five, lhzapata, with four, Thiago Silva and Cristiano Dewes, with two each. Nine more contributors had a PR merged. This stopped being “a little program I made over a weekend” a while ago.

I’m not going to dump 55 PRs here. I want to talk about the change that affects my daily use the most: the new ai-memory run.

The session is part of the project too

Code is the result that survived. It doesn’t preserve the entire investigation.

Git shows that you replaced Redis with SQLite. Maybe the commit explains part of it. But where is the Redis experiment? Where is the intermittent bug that only showed up with two workers? Who remembered that the first solution broke on Windows? Why did the team change its mind after three hours? Which workaround was temporary, and which one became the decision?

Much of that exists only in the agent session.

When I program with Claude Code or Codex, the session accumulates the project’s operational reasoning: questions, corrections, discarded attempts, test results, surprises, decisions, and changes in direction. The final code shows what stayed. The session explains how we got there.

And an LLM session, at the end of the day, is text. Claude Code writes JSONL. Codex does too. OpenCode uses SQLite. Pi, OMP, and Crush have their own formats and directories. Each harness packages the conversation differently, but the visible content is still messages and tool results.

Why should I leave the most expensive part of the work trapped inside the harness?

Anthropic can change limits, pricing, models, or formats tomorrow. OpenAI can too. An agent can be excellent this week and unbearable the next. I want to swap the engine without throwing away the whole trip.

That has been ai-memory’s thesis from the start: the programmer must remain independent of provider whims. Models and harnesses are replaceable. The project memory is mine.

Handoffs solved only half the problem

ai-memory already handled handoffs. I would close Claude Code, the hooks would consolidate the session, and the next Codex would receive a short summary with what had been done, open questions, and next steps.

That still exists and is still useful. Anyone who opens claude, codex, or opencode directly keeps the previous behavior. The new launcher is opt-in.

But a handoff is deliberately lossy compression. It preserves what seems most important at that moment. It isn’t meant to carry the entire session or resume each harness’s native session. If the summary left out an old attempt that became relevant again two hours later, you have to search the wiki or the records.

ai-memory run adds another layer: a managed workstream, one line of work that crosses harnesses.

Claude now, Codex in a little while

Basic usage looks like this:

cd ~/Projects/meu-projeto

ai-memory run claude
# work, then exit Claude Code normally

ai-memory run codex --yolo
# Codex continues the same line of work

ai-memory run claude --model opus
# return to Claude's previous native session

ai-memory run
# or let ai-memory choose the right harness to continue

You don’t need -- to separate arguments. Everything after the harness name goes to it, with one deliberate exception: --yolo belongs to the wrapper and is translated into the native dangerous option for Claude Code, Codex, OpenCode, Pi, or Crush.

Under the hood, ai-memory doesn’t try to convert a Codex file into a Claude file. That would be fragile and would probably break on the next update. Each harness keeps its own native session. The workstream connects those sessions to a portable ledger containing the visible part of the conversation.

Think of it this way:

Claude native session ─┐
Codex native session  ─┼─ workstream ─ portable context
OpenCode session      ─┤                 + full search
Pi native session     ─┘

The first time Claude enters that workstream, it gets a native session. When you switch to Codex, Codex gets its own native session and receives the portable delta it hasn’t seen yet. When you return to Claude, the launcher uses Claude Code’s own --resume and delivers only what happened in the other harnesses since the last visit.

This is very different from starting a new chat with a summary pasted into the prompt. Claude returns to its real session. Codex returns to its real session. ai-memory handles continuity between the two.

Managed mode currently supports Claude Code, Codex, OpenCode, Pi, Crush, and OMP. General ai-memory support is broader, with MCP and hooks for other clients, but that doesn’t mean every client already has a native-session adapter for run. Those are different contracts, and I prefer to make that explicit.

What goes into the workstream

When the harness exits, ai-memory reads the tail of the native session without modifying the original store. It imports visible user and assistant messages, completed tool calls with their results, compaction summaries, and a non-mutating Git checkpoint. Every event keeps its origin: Claude, Codex, OpenCode, Pi, Crush, or OMP.

Provider credentials, encrypted records, system and developer prompts, and hidden reasoning stay out. Private formats the adapter doesn’t understand stay out too and produce a loss annotation instead of letting the system pretend it imported everything.

Records pass through the sanitizer before entering ai-memory’s searchable ledger and immutable JSONL segments. The adapter opens native stores read-only; the harness itself remains the writer.

I don’t cram the entire session into the next prompt either. That would recreate the problem the project is trying to solve: too much raw context, too much cost, and too much noise. The next agent gets a size-limited recent delta. If an old decision matters again, the full ledger remains searchable:

ai-memory workstream-search "por que desistimos do Redis"
ai-memory workstream-search --limit 50 --json "migration que falhou"

Inside an ai-memory run, the workstream ID is already in the environment. The agent doesn’t have to discover some UUID.

And the ledger doesn’t replace the wiki. It handles operational continuity. Decisions, rules, procedures, and gotchas that need to survive for months still deserve consolidated Markdown pages. A raw session is evidence. A wiki is organized knowledge.

Can I keep more than one line of work?

Yes. The default workstream is called default, selected by repository and worktree. If I want an independent line for an investigation without contaminating the main work:

ai-memory run --new investigar-race claude

# later, continue that line with another harness
ai-memory run --workstream investigar-race codex

A lease prevents two windows from writing to the same workstream at once. On a normal exit, the launcher imports the tail of the session and releases it immediately. If someone kills the process without cleanup, the lease expires within 90 seconds and the next run resumes from the last confirmed cursor without duplicating imported events.

One stupid annoyance kept coming back: I would reopen a project after a few days and have no idea whether the newest session was in Claude or Codex. I’d guess, open one, realize the context was in the other, close it, and try again.

Now I just run:

ai-memory run

# or keep the same auto-selection in YOLO mode
ai-memory run --yolo

In an empty workstream, ai-memory looks for local sessions from that checkout in Claude Code, Codex, OpenCode, Pi, and Crush, finds the newest one, and opens the right harness for me. In an established workstream, server memory beats the file timestamp: it returns to the last harness attached to that work instead of accidentally adopting an old session that happened to receive a newer write. OMP remains available when selected explicitly, but it doesn’t participate in auto-selection yet.

On the first explicit run, the launcher can also offer existing sessions from the same checkout for adoption. You can start using it without abandoning the chat that was already open before you updated ai-memory.

Other new features I actually use

I promised I wouldn’t read the entire changelog out loud, but a few changes from this month deserve a mention because they reduce work for the programmer.

A briefing before the first question

A project can request an automatic briefing at the start of every session:

[briefing]
inject_on_session_start = "true"
max_chars = 4000

ai-memory assembles a package with pinned pages, _rules/, _slots/, and recent titles. The agent starts with the project’s rules and basic state instead of spending the first conversation rediscovering the architecture. It’s opt-in because it consumes context on every SessionStart, including after a Claude /clear.

Global preferences and cross-project search

Preferences that apply to all my work can now live in the reserved _global scope: coding style, preferred tools, personal rules, and conventions that don’t belong to one specific repository. Normal queries already combine that scope with the current project.

For meta-repos that need to query several sibling projects all the time, there is another opt-in:

[recall]
default_global = "true"

With that, memory_query and memory_recent without an explicit scope search every project. I don’t turn it on in every repo because gratuitous global search only adds noise.

Less static instruction, more Agent Skills

The routing block in CLAUDE.md or AGENTS.md got smaller. Detailed instructions for when to search memory, consolidate, save a decision, or create a handoff moved into managed Agent Skills. One command installs or updates both without trampling the rest of the file:

ai-memory install-instructions

That reduces drift too. When the protocol changes, I update the managed package instead of hunting down an old prompt copied across forty repositories.

Privacy before the network

Each repo can now exclude paths from capture:

[capture]
ignore_paths = ["private/**", "~/personal-notes/**"]

When an integration recognizes a file tool and the path matches, the event is discarded locally before spool, queue, network, or server. The limits are clear: this isn’t magic DLP, it doesn’t understand every shell command, and it doesn’t track content quoted in free-form text. But it handles the verifiable case without selling a fake guarantee.

There are also new integrations with Kimi Code, Grok Build CLI, Devin, and Zero, an OpenCode Zen/Go provider, finalize-session for Codex, and workspace-administration improvements. Again: having MCP and a hook doesn’t automatically mean having ai-memory run. The README separates those levels.

Bonus: ai-jail on the outside, YOLO on the inside

Just over a week ago I wrote about how I protect myself from agents deleting my stuff. My recommendation remains the same: YOLO mode gives the best experience, provided the system limits the possible damage.

ai-jail reached version 1.15.0 and now understands the ai-memory launcher. My favorite way to work has become:

ai-jail ai-memory run codex --yolo

Or, when I want ai-memory to choose which harness should continue:

ai-jail ai-memory run --yolo

Order matters. ai-jail stays on the outside so the launcher and child process remain inside the same sandbox. ai-memory run by itself manages the session, but it doesn’t create a sandbox.

--yolo gets rid of the harness’s approval ceremony. ai-jail handles containment: the current project is read-write, home is replaced with tmpfs, necessary parts of agent state are mounted selectively, and sensitive directories such as .ssh, .gnupg, and .aws stay outside the jail. The new support also keeps ai-memory’s local state writable so hooks can maintain spools and cursors between runs.

ai-jail recognizes both the ai-memory layer and the selected harness. If you have Codex-specific global configuration, for example, it still applies when the actual command is ai-memory run codex. Even the status-bar redraw adjustment understands that the child is Codex.

This combination takes care of both annoyances at once: the agent stops asking for confirmation on every command, and the session stops belonging to the agent. You get the speed without handing over your entire home directory.

One more thing: ai-usagebar grew too

When I published the original ai-usagebar, it monitored Claude, Codex, Z.AI, and OpenRouter in a Waybar widget or TUI. Version 0.14.0 already covers eleven usage, spending, or balance integrations.

Kimi got the two pieces of information that really matter for coding: weekly subscription quota and the rolling five-hour window. Kilo, Novita, Moonshot, and Grok show remaining balance. A separate Anthropic Console integration shows API spending for the month without conflating it with the Claude Code subscription. It makes clear that the Cost API doesn’t include Priority Tier.

You can also register multiple Anthropic accounts, see weekly limits for specific models such as Fable, and get a pace marker. The bar doesn’t turn red just because it reached 40%; it compares the percentage spent with how much of the window has passed. If I used 40% in 20% of the week, I’m moving too fast. That’s the useful information.

The project outgrew Waybar. It has a native macOS menu bar app, a GNOME extension, and a standalone TUI. The newest addition is a local Claude Code context monitor: I press c, choose one of the recent sessions, and see how much of the window it has consumed. It reads limited tails from local JSONL files and doesn’t invent a percentage when it can’t determine the window size.

In my workflow, the three end up working together. ai-usagebar shows which subscription still has room. ai-memory run switches harnesses without throwing away the work. ai-jail lets the chosen one run in YOLO without unrestricted access to the machine.

Updating

The installation pages for all three projects cover every method, including AUR, Homebrew, and release binaries:

• ai-memory
• ai-jail
• ai-usagebar

After updating ai-memory, reinstall the hooks for the harnesses you plan to use in managed mode. The three main ones in my case:

ai-memory install-hooks --agent claude-code --apply
ai-memory install-hooks --agent codex --apply
ai-memory install-hooks --agent opencode --apply

Crush doesn’t need a hook in managed mode; it receives context through a temporary file configured only for the launched process. The managed workstreams documentation covers installation, privacy, recovery, and native arguments for each adapter.

Conclusion

A month ago, ai-memory could already turn a session into a wiki and hand off to the next agent. Now it can manage the line of work itself: adopt an existing session, keep one native session per harness, carry visible history, resume each client in its own format, and keep the entire ledger searchable.

For me, that’s the value. The code contains the implementation that won. The session contains the decisions, failed experiments, gotchas, unexpected bugs, and changes of mind that produced that implementation. Throwing all of it away every time you change providers is wasteful.

A raw transcript doesn’t solve the problem by itself either. It’s large, repetitive, and expensive to stuff into every context. ai-memory keeps the evidence, delivers only the recent delta, and uses consolidation to turn what deserves to survive into short Markdown pages.

There are still new formats to support, platform rough edges, and plenty of testing ahead. The difference is that there is now a real foundation, with an acceptance test that calls actual harnesses, 14 outside contributors with merged PRs in a little over a month, and daily use pushing the design forward.

I rent LLMs and subscriptions from whoever is delivering the best service today. My project’s session stays with me.

The next day, goodalexander reproduced the same behavior on a disposable devnet: an rsync --delete-delay against / swept away /var, /etc and his validators’ state, corrupting the filesystem to the point of needing an OS reinstall. His conclusion: “you can’t use this thing in prod”.

Cases like these pop up every so often since coding agents went mainstream. And every time, the discussion degenerates into the same two extremes: on one side “see? AI is dangerous, never let it run anything on its own”, on the other “whoever lets an agent loose on their system deserves what they get”. I find both sides lazy. Let me tell you my actual experience and what I do about it.

Five months of marathoning, zero accidents

Since February I’ve been marathoning Claude Code, Codex and OpenCode. Almost every day, almost all the time, in very long sessions that sometimes span multiple days. Blowing past the limits of my Anthropic Max plan and my OpenAI Plus plan with room to spare. The concrete result so far: almost 40 new repositories on my GitHub and more than 500 thousand lines of code produced.

And for the past two months I’ve been running everything exclusively in “YOLO mode”. For those unfamiliar with the jargon: by default, these agents ask for permission before each command they’re about to execute in your terminal. YOLO mode turns that safety off. In Claude Code it’s the --dangerously-skip-permissions flag, in Codex it’s --yolo, in OpenCode you configure the permissions to approve everything. The agent runs whatever it wants, whenever it wants, without asking me anything.

In five months under this regime, not once has an agent deleted a file I didn’t ask for. Not once has it run a destructive command out of scope. The frustrations I have with agents are of a different nature (stubbornness, lazy solutions, context getting lost), annoying things but miles away from an rm -rf in my home.

So when I see these reports, my first hypothesis always goes to the same place: the prompt. For an agent to “go berserk” like that, in general the user wrote very bad instructions. Vague, ambiguous, asking for cleanup without defining what counts as trash, telling the agent to “fix it” without giving context. Lack of communication skills combined with lack of technical knowledge to notice the request was poorly formulated. The agent executes the instruction you wrote, with all the ambiguities you left in it.

That said, I do NOT trust LLMs completely. Nobody should.

The difference is that my distrust turns into engineering instead of turning into a tweet.

Layer by layer, this is how I sleep well at night.

Layer 1: sandboxing with ai-jail

When I genuinely suspect a session might do something stupid (I’m about to touch system scripts, I’m going to let the agent run for hours unsupervised on code that touches the filesystem), I open the harness inside ai-jail, a tool of mine, open source, written in Rust.

ai-jail is a sandbox wrapper for coding agents. On Linux it uses bwrap (bubblewrap, the same foundation as Flatpak), on macOS it uses sandbox-exec. The idea: the process sees a filesystem that looks normal, but only the current project directory is real and persistent. The rest of $HOME, the sibling directories, /tmp, everything lives in tmpfs and evaporates when the session ends. The agent’s state (~/.claude, ~/.codex etc) is mounted for real so it stays logged in and configured, but ~/.ssh, ~/.gnupg, ~/.aws and browser profiles never enter the jail.

Installing is one command:

# Arch Linux
yay -S ai-jail-bin

# macOS / Linux via Homebrew
brew tap akitaonrails/tap && brew install ai-jail

# or straight from crates.io
cargo install ai-jail

And using it is even simpler:

cd ~/Projects/my-app
ai-jail claude       # Claude Code in the jail
ai-jail codex        # Codex in the jail
ai-jail --dry-run claude  # shows the policy without running

If the agent decides to run rm -rf ~ in there, it deletes a tmpfs that was going to vanish anyway. My real home was never even mounted. For anyone starting out with YOLO mode without battle scars yet, it’s the cheapest way to make mistakes without consequences.

Layer 2: BTRFS and snapshots (the real safety net)

Now the main point of this post. I’ve been advocating for YEARS that Linux users should use BTRFS instead of EXT4. I made an entire Akitando episode about it in 2023, long before coding agents existed to take the blame. The argument was the same: your data needs to survive human error. An LLM running rm -rf in the wrong place is just a new category of human error, outsourced.

Why is BTRFS superior for desktops? Copy-on-write (CoW): the filesystem never overwrites a block in place, it writes the new version to another block and updates the pointers. Checksums for data and metadata, so silent bitrot gets detected instead of quietly corrupting your file. Transparent compression. Subvolumes, which work like flexible partitions without fixed sizes. And the most valuable consequence of CoW: lightweight snapshots.

A BTRFS snapshot is instantaneous and costs close to zero space the moment it’s created. It freezes the pointers to the current blocks instead of copying data. Only what diverges from that point on (new or modified blocks) starts taking up extra space. In practice you can take dozens of snapshots a day without feeling it. At this very moment my machine keeps 23 system snapshots, and the cost is the difference between them, a few gigs.

Scheduling snapshots

The two classic tools are Timeshift and snapper. Timeshift is the friendlier one: graphical interface, you set “how many snapshots to keep” per hour/day/week/month and it handles the rest. It expects the @ (root) and @home subvolume layout, which is the default for most distros that install on BTRFS today. snapper (born at openSUSE) is more granular: per-subvolume configs, automatic timeline, package manager integration to snapshot before and after every install.

# Timeshift: manual snapshot before a suspicious session
sudo timeshift --create --comments "antes de soltar o agente"

# snapper: create a config for /home and enable the timeline
sudo snapper -c home create-config /home
sudo systemctl enable --now snapper-timeline.timer

My setup runs Timeshift on a schedule, plus grub-btrfsd on standby (I’ll explain why in a moment).

Recovering deleted files

Here’s the magic that everyone who lost files to an agent wishes they had. A BTRFS snapshot is browsable like a regular directory. The agent deleted your project at 3pm? The 2pm snapshot still has everything:

# with Timeshift, snapshots are mounted under /run/timeshift
sudo ls /run/timeshift/backup/timeshift-btrfs/snapshots/

# found the snapshot from before the damage? copy it back and done
sudo cp -a /run/timeshift/backup/timeshift-btrfs/snapshots/2026-07-11_14-00-01/@home/akitaonrails/Projects/meu-app ~/Projects/

With snapper it’s the same thing via .snapshots inside the subvolume, and it also has snapper undochange to revert specific changes between two snapshots. Recovery in seconds, no drama, no forensic tooling.

What if the system won’t even boot?

goodalexander’s case went beyond losing files: the agent swept /var and /etc and the system became unusable, requiring an OS reinstall. With BTRFS not even that would be necessary. This is the scenario grub-btrfs exists for: a daemon that watches your snapshots and regenerates the GRUB menu with a boot entry for each one.

System won’t come up anymore? Reboot, hold the GRUB menu, pick “snapshots” and boot straight into yesterday’s snapshot, read-only. From inside it, run timeshift --restore, pick the good snapshot, reboot again. Entire system back to its pre-disaster state, in less time than it would take you to find the installation USB stick. In the absolute worst case (GRUB itself went down with the ship), any live USB mounts the BTRFS partition, points the default subvolume back to the good snapshot and that’s that.

What about macOS? And Windows?

Mac users have the direct equivalent: APFS, the default filesystem since High Sierra (2017), is also copy-on-write and also has lightweight snapshots. Time Machine is what manages them: with it enabled, macOS takes automatic local snapshots every hour and keeps the last 24 hours on the disk itself, independent of the external backup. And you can create one by hand before letting the agent loose:

# create an APFS local snapshot right now
tmutil localsnapshot

# list the existing snapshots
tmutil listlocalsnapshots /

To recover, open Time Machine itself (“Browse Time Machine Backups” in the menu bar): it browses the local snapshots even without any external disk plugged in, and you restore the file from there. If you prefer the terminal, mount the snapshot read-only with mount_apfs -s and copy it back. In other words, Matt Shumer’s case from the beginning of this post had a native solution on his own Mac: a snapshot from one hour earlier would have brought almost everything back.

On Windows the story is weaker. NTFS has the Volume Shadow Copy service (VSS), which feeds restore points and the “Previous Versions” tab, but it’s aimed at system files and rarely happens to be covering your data at the moment you need it. Nothing with the lightness and predictability of a scheduled CoW snapshot. If you develop on Windows, treat external backup as mandatory, no discussion (and the restic from the next section runs fine on Windows).

Layer 3: external backups with restic

Snapshots live on the same disk as the data. If the NVMe dies, they die together. Which is the other thing I’ve been repeating for years: everybody needs external backups, whether to an external hard drive or a NAS. I use a Synology on the local network, mounted via NFS, and documented the complete setup here.

On top of it runs restic, which in my opinion is the best backup tool for this purpose: deduplication, encryption, incremental snapshots and simple restores. My actual configuration is a script fired by a systemd timer every day at 3am. It checks the NAS is mounted, backs up /home and /mnt/data/Projects skipping caches (node_modules, Rust’s target/, __pycache__ and friends, all in an excludes file), and then applies the retention policy: 7 daily, 4 weekly, 6 monthly, 1 yearly.

Reproducing the essentials looks like this:

# once: create the repository on the NAS
restic init --repo /mnt/nas/desktop-backup

# every day (via cron or a systemd timer):
restic -r /mnt/nas/desktop-backup backup ~ /mnt/data/Projects \
    --exclude-file=~/.config/restic/excludes --exclude-caches

restic -r /mnt/nas/desktop-backup forget \
    --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --keep-yearly 1 --prune

And if the truly bad day arrives (destructive agent, dead disk, ransomware, the cause doesn’t matter):

# list the available snapshots
restic -r /mnt/nas/desktop-backup snapshots

# restore a specific file or directory
restic -r /mnt/nas/desktop-backup restore latest \
    --target /tmp/recuperado --include /home/akitaonrails/Projects/meu-app

# or mount the whole repository as a filesystem and browse at your leisure
restic -r /mnt/nas/desktop-backup mount /mnt/restic

Notice the layered architecture: the BTRFS snapshot solves the accident from minutes ago in seconds. restic solves the disaster from days ago, including dead hardware. An AI agent would have to be very dedicated to punch through both layers, and even then there would still be yesterday’s copy on the NAS, which it can’t even reach.

What about companies? Professionalism

Everything above is about my personal machine. Now let’s raise the bar: corporate environments.

Rule number one is simple and non-negotiable: no AI agent should ever have access to production. Ever. No direct SSH into production servers, no production database credentials, no admin tokens for production services. If your agent can run a DELETE against the database that serves customers, the problem stopped being the AI a long time ago: any intern with the same access is the same time bomb, just with a slower typing speed.

Agents in staging, on the other hand, I advocate for. That’s what staging is for. But even in staging there’s a right way: you resist the temptation of prompting one-shot actions (“run an apt install over there”, “do a systemctl restart”, “connect to postgres and execute this”). A loose command executed by hand is knowledge that evaporates. Your infrastructure needs to be automated and reproducible: Ansible, Kubernetes, Terraform, whatever makes sense for your stack. The agent’s role becomes writing and refining those recipes, which live versioned in git.

A small example, right here from my desk

I have a gaming environment on my main PC, but I refuse to mix emulator packages with my software development environment. So I isolated gaming inside a distrobox. For those who don’t know it: distrobox creates containers (via podman or docker) that integrate with your desktop as if they were native. They share your home (or a dedicated home), GPU access, Wayland, audio. In practice it’s a complete distro inside your distro, with a separate package space.

distrobox-gaming is a repository of Ansible playbooks that builds an Arch box called gaming from scratch: ES-DE as the frontend, standalone emulators (shadPS4, RPCS3, PCSX2, Dolphin, DuckStation, Eden and a dozen more), RetroArch cores, per-game optimized configs, launcher shortcuts on the host. And distrobox-llm does the same for a local LLM work box: CUDA, cuDNN, Ollama, whisper.cpp and LM Studio isolated in a box with --nvidia, while the host only carries the driver. A CUDA major version upgrade no longer rattles my development environment.

Who wrote the overwhelming majority of these playbooks? The agents. Instead of asking “install RPCS3 for me”, my prompt is “write the idempotent Ansible recipe that installs and configures RPCS3, run it, verify the result and fix it until it passes”. Here’s a real excerpt from the role that creates the LLM box:

- name: Check if distrobox exists
  ansible.builtin.shell: "distrobox list 2>/dev/null | awk '{print $3}' | grep -qx {{ dl_box_name }}"
  register: _box_exists
  changed_when: false
  failed_when: false

- name: Create distrobox
  ansible.builtin.command: >-
    distrobox create
    --name {{ dl_box_name }}
    --image {{ dl_image }}
    --home {{ dl_box_home }}
    {{ '--nvidia' if dl_nvidia_enabled else '' }}
  when: _box_exists.rc != 0

Idempotent: it checks whether the box exists before creating it, running it twice gives the same result. If my PC catches fire tomorrow, I recreate both environments in full with one ansible-playbook site.yml in each repo. The knowledge lives in the recipe, versioned, auditable. Zero commands lost in shell history.

Scaling the same principle to production

At a company, swap distrobox for Kubernetes and the principle is identical. The agent writes the manifest, tests it on the staging cluster, you promote it to production manually:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: minha-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: minha-api
  template:
    metadata:
      labels:
        app: minha-api
    spec:
      containers:
        - name: minha-api
          image: registry.exemplo.com/minha-api:v42
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
          resources:
            limits:
              memory: 512Mi

The professional flow: the agent produces and adjusts the manifest (or the Helm chart, or the Terraform module), applies it to staging (kubectl apply -n staging), runs the tests, watches for side effects, bugs, unintended behavior, and iterates until you’re satisfied. Then YOU, a human, promote it to production (via a reviewed PR in a GitOps flow, or a manual and deliberate kubectl apply), monitoring every step. The agent did all the heavy lifting: the artifacts, the procedures, the checklists. You can even ask it to generate the audit documentation at the end. But the finger that presses the production button has a name on a payroll.

Even the “simple” maintenance SQL

A case that looks harmless and bothers me a lot: maintenance SQL commands in production. Plenty of people have always run those by hand, straight into the production client, and are now asking the agent to write AND execute them. That is unacceptable, with or without AI. Your system should have a migrations workflow: the change becomes versioned code, runs in staging first, gets validated, and only then executes in production inside the normal deploy process.

And “production”, by definition, means two things many companies pretend to have. First: real backups, tested, with rehearsed restores.

Never run anything in production that you can’t recover from.

Second: monitoring. If you have no visibility into the state of the system, you don’t have production, you have a server plugged into an outlet and a prayer.

Monitoring: even on my humble PC

And monitoring is so much a part of the discipline that I apply it even to my personal machine. I recently developed a system health widget for my clock-tui (my maintained fork of the original clock-tui, with command widgets in clock mode). It sits open in a corner showing this:

One verdict line (“all systems healthy”) and the state of everything this post described: the restic backup ran 19 hours ago and the next one is at 03:03; Timeshift keeps 23 snapshots; the development cache cleanup ran 32 hours ago; the BTRFS scrub is up to date on each filesystem, with a recent trim, healthy allocation and zero I/O errors; plus zombies, load, memory and each disk’s usage. The widget (tclock-system-health) ships with the repository and the AUR package, and detects most of this on its own.

Behind it are the automated maintenance jobs, all systemd timers: the daily restic at 3am; dev-cache-clean (on the 1st and the 15th) sweeping orphaned Rust target/ dirs and the yay cache, which together give back dozens of gigs; the monthly per-filesystem btrfs-scrub validating checksums; the weekly fstrim. None of it requires me to remember anything. When one of them is late or fails, the widget changes color right in my face.

This is the home-grade level, proportional to a personal PC. At a company you go full-blown: Prometheus collecting metrics, Grafana drawing the dashboards, Alertmanager waking up the on-call person at 3am. The scale changes, the principle is the same: the state of the system visible at all times, and someone (or something) getting notified when it goes off the rails.

Conclusion: discipline

Go back to the two tweets at the beginning. In both cases, a single wrong command caused real loss, and the public discussion became “who do I trust more”. The right question is a different one: why does a single wrong command, from any origin, have the power to cause unrecoverable loss on your machine?

Being a professional is being disciplined, and discipline starts at home. My personal PC operates with the same rigor I would demand from a corporate environment: a filesystem with lightweight scheduled snapshots, recoverable boot via GRUB, daily external backups with a retention policy, a sandbox for suspicious sessions, isolated environments rebuildable from versioned recipes, automated maintenance and a monitor that warns me when any piece falls behind. Monthly maintenance cost of all this: close to zero. It was set up once (in good part by the agents themselves) and runs on its own.

With these layers, the question in the title almost loses its meaning. The agent deleted a directory? Snapshot from an hour ago, two minutes of recovery. Destroyed the system? Boot into a snapshot via GRUB, restore, ten minutes. Fried the disk along with it? restic on the NAS, yesterday’s backup. In five months of YOLO mode I never needed any of these nets for an AI accident. But I sleep well precisely because they’re there.

An LLM running loose on your system is just the most recent stress test of your discipline. If an out-of-control agent can cause permanent loss to your data, the vulnerability was always there, waiting for a mistake of yours, a bad disk or a ransomware. The agent was just the messenger that arrived first.

I’ll repeat something important before someone starts cloning all my repositories thinking they are 1.0 products: most of the frank-* projects on my GitHub are proofs of concept. Experiments. Some work well for me, in my environment, in my workflow. That does not mean they are ready to become a critical dependency in your company tomorrow morning. Want to play, contribute, study? Great. Just don’t confuse “I published it on GitHub” with “this is production ready.”

There are exceptions. FrankMD, for example, received a decent amount of contributions, tests, polish, real bug fixes, real use. Today it is much more stable than it was in the first post. Still, the point stands: these projects were born as a vibe-coding lab, not as a 3-year product plan with roadmap, enterprise support, and SLA.

This post is a roundup of what I learned in that lab. A few of my tools, a few habits, a few recommendations. Nothing mystical. No “revolutionary new way to program.” Old engineering with new tooling.

First: stop collecting agents

If you are a normal developer, you do not need 12 agents, 40 wrappers, 7 orchestrators, and a Kubernetes diagram to choose who gets to write an if.

In practice, focus on Claude Code, Codex, or opencode. That’s it.

Yes, Gemini CLI exists. Yes, Cursor exists. Yes, Windsurf, Crush, OpenClaw, Pi, Aider exist, and tomorrow another half-dozen will show up. I tested a bunch. Read my LLM benchmark posts, especially “LLM Benchmarks Part 3: DeepSeek, Kimi, MiMo”. The conclusion is boring and obvious: today, the best cost-benefit options for heavy programming are Opus 4.7 and GPT 5.5 on subsidized Pro/Plus/Max plans. Nothing comes close when the job is spending several hours a day with a real coding agent.

Paying directly for tokens is expensive. Paying for a subsidized monthly plan is much cheaper. That’s why I keep alternating between Claude Code and Codex: not because I want “multi-agent architecture,” but because the plans have limits and I work many hours in a row.

Are DeepSeek v4 and Kimi 2.6 cheaper? Yes. Are they usable? Yes. I like them for several cases. But for Agile Vibe Coding the way I’ve been advocating since “From Zero to Post-Production in 1 Week”, they are still lacking. They stumble more on continuity, long refactors, tests, understanding the whole project. Can you use them? Sure. But if the goal is consistent productivity, Opus and GPT are still the bar.

Running an open-source model locally is neat. I played with that a lot in the Minisforum MS-S1 Max with AMD AI Max+ 395 review. For one-shots, studying, playing with local inference, it’s fun. For Agile Vibe Coding all day, every day, it is still not practical. Latency, context, quality, setup maintenance, VRAM, all of it collects tax.

Running multiple LLMs in parallel is not practical either, the whole “planner + executor + reviewer + judge” routine. I tested that in “LLM Benchmarks: Is It Worth Mixing 2 Models?”. The idea looks nice on paper. In practice, it increases cost, latency, error surface, and the gain does not pay for the complexity.

The secret is not having a bunch of agents. Forget OpenClaw or Pi for day-to-day programming. The secret is engineering process. XP. Tests. Clean Code for AI Agents. CI. Pair programming. Constant refactoring. Small code. Automated deploy. Fast feedback.

Tools help. Engineering wins.

ai-jail: autonomy with a fence

The first project I want to highlight is ai-jail. It is a sandbox wrapper to run AI agents with restricted system access. On Linux it uses bubblewrap (bwrap) and Landlock. On macOS it uses sandbox-exec. The idea is simple: the agent sees the environment it needs to work, but does not go rummaging through your whole system.

Do I use it every day? Yes. Do I use it always? No.

When I know I am not doing anything risky, I open claude or codex directly. If I am touching a simple project, just running tests, editing markdown, refactoring local stuff, often I do not bother. In more than 600 hours of intense Agile Vibe Coding, more than half a million lines of code and documentation, I never had one of those folklore cases of an LLM destroying my host system in some unrecoverable way.

And look, I explicitly used agents to configure my Omarchy. ZSH, Hyprland, Waybar, terminal configs, login scripts, all of it. They never did anything I did not ask for.

Those stories of “the agent deleted my whole home by itself” make me raise an eyebrow. In my experience, when you ask it to delete something dangerous, Claude and Codex ask for confirmation. You have to say yes. If you said yes without reading, that is not LLM black magic. That is user in zombie mode.

Nothing is guaranteed, of course. Hence ai-jail.

My favorite use is combining ai-jail with the harness’ no-brakes mode:

ai-jail claude --dangerously-allow-permissions
ai-jail codex --dangerously-bypass-approvals-and-sandbox

It sounds contradictory, but it makes sense. I remove the confirmation friction inside the agent, but put a fence at the operating-system level. The agent can work fast inside the project, but the host filesystem is essentially read-only. The current directory is read-write. Whatever I explicitly map with --rw-map is also read-write. The rest is not to be touched.

The ai-jail README sums it up well: it is a sandbox wrapper for agents like Claude Code, GPT Codex, OpenCode, and Crush. On the first run it creates a .ai-jail in the project, which can be committed. It supports --dry-run to see mounts before executing, --lockdown for a stricter mode, --private-home to hide real dotfiles, --mask .env to hide sensitive files inside the project itself, and isolated browser profiles for Chromium/Firefox.

Do not sell this as absolute security. Process sandboxing is not a VM. Kernel bugs exist. Side channels exist. macOS has limitations. The README itself is clear: if you need to isolate a truly hostile workload, use a disposable VM. I do not use ai-jail as “military-grade armor.” I use it as another layer, good enough for a development workflow.

And even inside the project, everything is Git. I push frequently to GitHub or to my private Gitea. So the realistic worst case is the agent destroying the project directory. Annoying? Yes. Catastrophic? No. I clone again. I come back from the remote. I redo what was local. If .git gets corrupted, I delete everything and clone again.

Secrets also have a copy outside. .env, tokens, keys, everything that matters sits in Bitwarden. Self-hosted in Vaultwarden, of course. So if I lose the local directory, I did not lose the keys to the kingdom.

The most common risk is not the agent deleting everything. It is you leaking a secret to Git. That happened to me more than once. You run git add ., forget a .env, push to the remote, congratulations. It happens. That’s why you must look at git status, git diff --cached, and think before pushing.

Even when it happens, LLMs are very competent at helping rewrite history. I ask them to clean the secret from Git, force-push, review that it disappeared, and then I rotate the key. It is not pretty, but it is manageable.

So yes, I recommend using Claude/Codex with dangerous permissions inside ai-jail. Is there a 0.001% chance of an unrecoverable accident? There is. But if you are a good engineer, that should not kill you. I have layers: automatic Btrfs snapshots, restic to my NAS, NAS archiving offsite to AWS Glacier, remote Git, Bitwarden. No tool replaces backups.

ai-memory: context that survives the harness

The second is ai-memory, which I explained in detail in “I Built a Memory System for Coding Agents: ai-memory”.

The motivation is simple: harnesses lose context. Claude Code compacts. Codex compacts. opencode compacts. The session ends. You open another agent and it does not know what happened in the last 4 hours. If you only use one harness, maybe it does not bother you much. If you alternate between Claude and Codex like I do, it gets annoying fast.

I wanted a long-term memory consolidator that worked across different harnesses. Something that allowed handoff between Claude, Codex, and opencode without me manually writing HANDOFF.md every time. Something that captured prompts, tool calls, and session events through hooks, consolidated them into markdown pages, indexed with SQLite/FTS5, and exposed everything through MCP when the agent needed to query it.

Another motivator was what I explained in “Is RAG Dead? Long Context, Grep, and the End of the Mandatory Vector DB”. For code projects, simple text almost always solves more than fancy vector DB architecture. Markdown, grep, SQLite FTS5, long context, and good files in docs/ already take you far. ai-memory follows that line: compile memory into text, leave it on disk, index it simply, and only call an LLM when consolidation is worth it.

ai-memory was not made to be a user-browsable knowledge base. It has a read-only web UI, yes, but that is for auditing and inspection. The memory is optimized for LLM consumption. It is an internal wiki the harness can query when it thinks it needs to. It is a place where I can explicitly ask “save this for the next session” and expect it to survive longer than Claude or Codex’s default compaction.

The README sums it up well: coding agents lose all context when the session ends; ai-memory gives them a shared persistent wiki. Every prompt, tool call, and decision can be captured automatically. At the end of the session, relevant pages are rewritten as coherent narrative. In the next session, another agent can receive a handoff already prepended into the context.

This is useful when you close Claude at 6pm, open Codex the next day in the same directory, and want it to know you were testing session cookies because JWT rotation had run into trouble. Or when you return to a project six weeks later and do not remember why you discarded Redis.

But do not confuse it with canonical documentation. If you did important research you do not want to lose, ask the agent to write markdown in docs/ inside the project. Architecture decision, benchmark, library analysis, deploy runbook, anything that must survive with guarantees should become an explicit file in the repo. That is simpler, auditable, and versioned.

ai-memory covers the middle band: transient information that might matter later. A weird bug that appeared. The reasoning that led to a decision. An environment gotcha. A session summary. Things you do not want to turn into official docs yet, but also do not want to throw away.

It is still beta. I use it in personal production, but it needs many more users beating on it. The most polished integrations today are Claude Code, Codex, and opencode. Gemini CLI, OpenClaw, and exotic MCP clients still need more testing. PRs are welcome. Bug reports too. “I installed it and it broke on my setup” is exactly the kind of feedback that reveals a wrong assumption.

ai-usagebar: knowing when to switch horses

As I said above, I prefer using Anthropic and OpenAI’s subsidized plans. The problem is that if you do real Agile Vibe Coding, you hit limits. Daily limit. Weekly limit. Session limit. Limit that changes. Limit that does not show up clearly anywhere.

I was using claudebar, which is good, but only covers Claude. I wanted to see the main vendors in one place. That became ai-usagebar, which I introduced in “I Built a Waybar Widget for Omarchy to Monitor LLM Plan Usage: ai-usagebar”.

It is a Waybar widget and Rust TUI to monitor Anthropic Claude, OpenAI Codex/ChatGPT, Z.AI GLM, and OpenRouter usage. For Claude and OpenAI, it reads the OAuth credentials the official CLIs already wrote. For Z.AI and OpenRouter, it uses API keys. It shows session percentage, reset, limits, balance, and lets you switch the primary vendor.

The value is banal and therefore useful: I glance at the bar and know whether I should continue in Claude, hand off to Codex, or top up OpenRouter credit. I do not want to discover I hit the weekly limit in the middle of a large refactor.

There is also a standalone TUI:

If you do not use Omarchy, Hyprland, or Waybar, you can still run ai-usagebar-tui in any terminal. SSH, tmux, normal terminal, whatever. The bar is convenience. The TUI is the universal form.

ghpending: GitHub pending stuff without the ritual

After the marathon, I ended up with dozens of ai-* and frank-* repos on GitHub. That creates an annoying problem: issues and pull requests start appearing. A contributor opens a PR. Someone reports a bug. Someone else sends a suggestion. If I have to open the browser, enter repo by repo, filter tab by tab, I will postpone it. And if I postpone it, I go weeks without answering contributors.

Yes, I could use gh, the official GitHub CLI. I do use it. But I wanted something dumber and faster: a short command to print a digest of everything pending in the repos I chose to monitor. That became ghpending, which I described in “I Built a CLI to Check My GitHub Pending Stuff: ghpending”.

That is it: ghpending add to choose repos, ghpending to see the digest, ghpending list, ghpending rm. Without auth it works with GitHub’s 60 req/h anonymous limit. With GITHUB_TOKEN=$(gh auth token) ghpending, it goes up to 5,000 req/h.

The point is not replacing GitHub. It is reducing friction. If I can run one command in the terminal and see “there are 3 PRs and 2 issues to look at,” I look. If it depends on browser ritual, notifications, and tabs, it waits.

And Claude/Codex are very good at this kind of work. You can ask:

“Check the open pull requests, review the code, see if it compiles, run the tests, add tests if missing, rebase from master if needed, merge and close.”

Or:

“Check the open issues, evaluate whether there is a real bug, reproduce it if possible, propose a fix, answer the user.”

They read the PR, understand the diff, run tests, rebase, solve simple conflicts, write the contributor response. You still keep your brain on. You are delegating mechanical work you already know how to do.

Refactoring: ask explicitly, several times

Claude and Codex are very good at refactoring, but do not assume they will do it automatically the way you would. I usually start projects or features with explicit instructions:

“Use Rust best practices. Avoid unnecessary duplication. Modularize only where it makes sense. Add unit tests for every new feature. Follow Clean Code principles. Do not create an abstraction before it is needed.”

After a large feature, a large fix, or a few hours of development, I stop and ask:

“Now that we touched a lot of code, re-evaluate it carefully. Delete dead code. Refactor obvious duplication. Add missing tests. Remove magic numbers. Check if any modules are too large. Do not change behavior without tests.”

Before release:

“Before publishing this version, do a sanity audit. Look for secret leaks, dangerous permissions, destructive commands, path traversal, unnecessary unwraps, missing validation, and anything that looks like an obvious vulnerability.”

Does that guarantee security? Of course not. Not even close. But it removes a lot of dumb mistakes. It is another layer. I like running this audit with Claude and then with Codex, because each one finds different things. Bugs still pass. Security is process, not a magic ritual.

Disposable experiments: code got cheap

Before choosing a library, framework, architecture, model, or service, I like creating experiments/.

Example:

“Before choosing between Qwen and DeepSeek, create a disposable prototype in experiments/ for an A/B test. Document the analysis in docs/ with result, cost, latency, quality, and recommendation.”

This changed how I decide. Before, many engineering decisions became opinion, feeling, faith in somebody else’s benchmark. Now code is cheap. I ask the agent to make two or three versions, run tests, measure, document, throw away what does not work.

Prototyping got genuinely fast. Frank Karaoke is a good example: turning YouTube into a karaoke app was the kind of idea I would maybe leave in a mental list for months, waiting for “a free weekend” that never arrives. Now I can open experiments/, ask for a rough prototype, test the technical path, and decide whether it deserves to become a project. Look at my other 2026 posts about frank-* and ai-* projects: almost all of them started like this, as disposable code that proved something before earning a name.

But cheap prototypes do not mean one-shot. I already wrote in “Why LLMs Aren’t Giving You the Result You Expect”: a good prompt is an iterative conversation. You provide context, show references, point out constraints, read the result, correct direction, ask for a rewrite. If you throw in a vague sentence and expect a finished product, that’s on you.

I learned this by taking a beating too. In the Frank Yomik post I described my first real vibe-coding failure: when the direction is wrong, insisting on the same prompt just digs the hole deeper. Sometimes you need to reduce scope, isolate the problem, create a test, change strategy. LLM does not turn a bad plan into good engineering.

And there are domains where you need to study along with it. In the DriveClub and shadPS4 post, AI almost sent me in every wrong direction because the problem required understanding rendering, gamma, shaders, buffers. The tool helps you explore, but you still decide whether the explanation makes sense. If you do not understand enough to verify, you are just accepting a pretty guess.

That is also why I keep repeating the idea from “Software Is Never Done”: deploy is not the finish line. The prototype becomes a product when it handles bug reports, maintenance, refactoring, docs, releases, rollbacks, users complaining. LLM helps a lot with that boring cycle. But the cycle still exists.

If it is testable, test it. If it can be measured, measure it. If it cannot be measured, at least write down the assumptions. The important thing is not choosing just because it “seems better.”

Cheap code also means detachment. Make code to throw away. Make an ugly prototype. Make a disposable benchmark. Ask the agent to document what it learned in docs/decision-qwen-vs-deepseek.md, then delete experiments/ if you want. The document stays. The lesson stays.

LLMs are also very good at documentation. Use that. Ask it to document everything. Why we chose PostgreSQL instead of SQLite in this case. Why the deploy uses a multi-stage Docker image. Why the service runs behind Cloudflare Tunnel. Why that sysctl exists. Even if you delete half of it later, the cost of writing fell near zero.

Automated deploy or you will stop maintaining it

Every project of mine that matters has automated build. Many run in my homelab, as I described in “Migrating my Home Server with Claude Code”. Almost every project has a bin/deploy that builds a Docker image, pushes it, rotates it on the server, applies migration if needed, and validates healthcheck.

Claude and Codex are excellent at deploy. They read bin/deploy, understand Dockerfile, edit GitHub Actions, adjust release workflows, fix binary signing, update Homebrew taps, generate checksums. And yes, I ask Claude/Codex to SSH into my homelab and redeploy Docker containers. They are very good at that. ai-jail, for example, has GitHub Actions to build signed binaries for Linux and macOS.

If you have dozens of projects, the more automated the better. I rarely type admin commands in the terminal by myself. I ask the LLM to do it, observe, approve what is dangerous, and then ask:

“Document what was done and why it was done.”

This applies to the homelab and my workstation. My Omarchy is customized through Claude: ZSH, Hyprland, Waybar, scripts, shortcuts, themes, integrations. Even my gaming/emulation setups fall into this, as I showed in the retro racing games running on Distrobox post. This is a case where I normally do not use ai-jail, because I actually want to touch the host. So I look at commands, read diffs, approve slowly. Even then, I never had the agent break my system in an unrecoverable way. Quite the opposite. My PC has never been more stable and documented.

Days later, when I forget why I configured something that way, the context is in markdown, Git, ai-memory, or the project history itself. I can ask and the agent has something to pull from.

Even this post was written this way

This is how I write these posts now. I dump a huge messy block from my brain into Claude. I ask it to read recent posts to calibrate style. I ask it to check the projects directly and elaborate the technical parts. I ask it to use the latest screenshots, upload to S3 when needed, link previous posts, review the tone.

Then I read and edit. I cut what sounds generic. I replace sentences that sound like release notes. I put my rants back in. The result is still my text; I just spend energy on what matters: deciding what to say, correcting nuance, cutting nonsense.

“But did you test Pi?”

Every time I mention an LLM or LLM tool, someone shows up in the comments with the same question: “but did you test Pi?”, “but did you test DeepSeek?”, “but what about Qwen?”, “but what about the new model that came out yesterday?” Every. Single. Time.

It is annoying as fuck. And almost always it comes from three kinds of people: someone who tested nothing and wants to outsource the work, someone who already chose a tool and wants me to validate their choice, or a fanboy treating an LLM vendor like a soccer team. They all sound the same. NPC repeating tutorial dialogue.

Software engineers should not decide based on other people’s opinions. Not even mine. If you choose a tool because “Akita said so,” you understood it wrong. I advocate Claude Code and Codex because I used them for hundreds of hours, in real projects, publishing code and post-mortems of what worked and what failed. And even then I did not stop at opinion.

I built my own automated benchmark: llm-coding-benchmark. I update it when a popular vendor releases a new version. I run comparable scenarios. I publish results. Then I adjust my opinion based on the data. That gives me enough ground to say that, in my workflow, Opus and GPT keep winning. Not because I woke up wanting to defend some billionaire company’s logo.

If your first reaction was “but did you test Qwen?”, great. Test it yourself. Run the benchmark. Create a better scenario. Send a PR. Show numbers. Show cost. Show latency. Show where it failed. Show where it won. Bring new data.

Loose opinion is irrelevant. “It works for me” does not scale. “I like it better” does not matter. “In my one-shot prompt it was better” is an anecdote. Engineering starts when something can be reproduced, compared, and acted on.

So it is simple: bring actionable data or shut the hell up. I do not need vendor fan clubs in the comments. I need people testing, measuring, and contributing new results.

Final checklist

Short summary, because this post is already long:

• Focus on Claude Code, Codex, or opencode. Stop collecting agents.
• Use Opus 4.7 and GPT 5.5 through Pro/Plus/Max plans when daily productivity matters.
• DeepSeek, Kimi, and local models are useful, but still do not replace the main workflow.
• Agile Vibe Coding is XP with LLM: tests, Clean Code, CI, pair programming, and deploy.
• Use ai-jail when you want agent autonomy with a filesystem fence.
• Combine ai-jail with dangerous Claude/Codex permissions when the project is protected by Git.
• Have real backup: Btrfs snapshots, restic, NAS, offsite, Git, Bitwarden.
• Review git add, git diff --cached, and pushes so you do not leak secrets.
• Use ai-memory for transient context and handoff between agents.
• Write canonical documentation in docs/ when information needs to survive with guarantees.
• Use ai-usagebar to know when to switch from Claude to Codex, or when to top up OpenRouter.
• Use ghpending so you do not abandon issues and PRs.
• Ask for refactoring explicitly after large features.
• Run a security audit before release, preferably with more than one model.
• Create disposable prototypes in experiments/ before deciding by faith.
• If you disagree with a benchmark, run llm-coding-benchmark and bring new data.
• Document decisions in markdown. Code got cheap. Documentation too.
• Automate deploy. If it depends on a manual ritual, you will stop doing it.

In the end, it is the same advice as always: tools change, engineering does not. LLM increases leverage. If you already had good habits, you will produce more. If you did not, you will just produce mess faster.

And yes, this changes the interface of the work. I already wrote about that in “VS Code Is the New Punch Card”: polishing pixels in an editor is now old-programmer nostalgia. The hard part is writing intent correctly, reviewing execution without being lazy, measuring results, throwing away cheap code, and not confusing opinion with data.

–

In January I published a ~170-line shell script that built a sandbox with bubblewrap to run Claude Code, OpenCode, Crush and any other AI agent. It worked. It solved the problem. But it was a bash script dropped in ~/.local/bin/ that you had to copy, paste, and pray you wouldn’t need to customize too much.

Two months of using that script every day showed me its limits. I wanted per-project configuration. I wanted macOS support for the devs on my team. I wanted to stop editing bash arrays every time I needed an extra directory. And I wanted something someone could install with brew install or cargo install in 10 seconds, without reading 170 lines of script.

Result: ai-jail. A Rust tool, ~880KB, 4 dependencies, 124 tests, that does exactly what that script did and more. I’ll explain what changed and why you should be using it.

The Problem (again, for those who skipped the previous post)

AI coding agents need access to your filesystem. They need to run compilers, linters, grep, ls, make, cargo, npm. The minimum to be useful. The problem is that along with that access comes the ability to read ~/.aws/credentials, exfiltrate your SSH keys, or run an rm -rf outside the project directory.

It isn’t paranoia. Supply-chain attacks are real. Every other week some NPM, PyPI or RubyGems lib gets compromised. If the agent runs npm install and a malicious post-install script tries to exfiltrate your data, the only thing between the attacker and your credentials is whatever barrier you set up beforehand.

The answer is a sandbox. Specifically, one that lets the agent work in the project directory with the tools it needs, but makes the entire rest of the system invisible.

From Script to Tool

The shell script from the previous post already solved this with bubblewrap. ai-jail solves the same problem, but addresses the limitations that two months of daily use revealed:

The core logic is the same: bubblewrap creates isolated PID, UTS and IPC namespaces, mounts $HOME as an ephemeral tmpfs, and only mounts the project directory with write access. The difference is that all of that is now configurable without editing code.

Installation

Four ways:

# Homebrew (macOS and Linux)
brew tap akitaonrails/tap && brew install ai-jail

# Cargo
cargo install ai-jail

# Mise
mise use -g ubi:akitaonrails/ai-jail

# Direct binary from GitHub Releases
curl -fsSL https://github.com/akitaonrails/ai-jail/releases/latest/download/ai-jail-linux-x86_64.tar.gz | tar xz
sudo mv ai-jail /usr/local/bin/

On Linux, bubblewrap needs to be installed separately: pacman -S bubblewrap (Arch), apt install bubblewrap (Debian/Ubuntu), dnf install bubblewrap (Fedora). On macOS no extra dependency is needed.

Basic Usage

cd ~/Projects/my-app

# Run Claude Code inside the sandbox
ai-jail claude

# Run Codex
ai-jail codex

# Run OpenCode
ai-jail opencode

# Plain bash for debugging
ai-jail bash

# Any command
ai-jail -- python script.py

On the first run, it creates an .ai-jail file in the project directory:

# ai-jail sandbox configuration
# Edit freely. Regenerate with: ai-jail --clean --init

command = ["claude"]
rw_maps = []
ro_maps = []

This file is committable to the repo. When another dev on your team clones the project and runs ai-jail, the same configuration applies.

If you want to add extra directories, you can do it from the CLI or directly in the TOML:

# Extra directory with write access
ai-jail --rw-map ~/Projects/shared-lib claude

# Extra read-only directory
ai-jail --map /opt/datasets claude

Want to see what the sandbox is going to do without running anything?

ai-jail --dry-run --verbose claude

It shows every mount point, every isolation flag, the full bubblewrap command. No surprises.

Why Bubblewrap on Linux

I evaluated the alternatives before deciding. The full analysis document is in the repository, but the short version is:

Bubblewrap (bwrap) is the sandbox Flatpak uses to isolate every desktop app. ~50KB binary, ~4000 lines of C, maintained by the GNOME team. It runs without root using CLONE_NEWUSER to create namespaces without elevated privileges. It’s packaged in every relevant Linux distro and tested at scale by millions of Flatpak installations.

I considered and rejected the alternatives. Firejail requires setuid root, and trusting setuid to protect against agents already running on your system is contradictory. nsjail and minijail are designed for production environments (Google uses them internally), too complex for a dev workstation. systemd-nspawn requires root and is meant for system containers, not for isolating a single process.

Landlock is a different case. It doesn’t replace bubblewrap — it has nothing to do with namespaces or mount isolation. But it complements. Landlock is a Linux Security Module that controls access at the VFS level, independent of mount namespaces. That closes vectors bwrap alone doesn’t cover: escape paths through /proc, symlink tricks inside permitted mounts, and it serves as a safety net against bugs in the namespace machinery itself. As of v0.4.0, ai-jail applies Landlock automatically on kernels 5.13+ as defense-in-depth. It uses ABI V3 (Linux 6.2+) with graceful degradation to V1 on older kernels, and turns into a silent no-op if the kernel doesn’t support it. If it causes problems with some specific tool, --no-landlock turns it off.

Bubblewrap hits the exact sweet spot: real isolation without root, on every distro, and simple enough to wrap in an 880KB binary.

What the Sandbox Does on Linux

When you run ai-jail claude, this is what happens:

The agent runs in isolated PID, UTS and IPC namespaces, with hostname ai-sandbox, and dies automatically if the parent dies (--die-with-parent).

The filesystem is mounted in a specific sequence (bubblewrap is order-dependent). /usr, /etc, /opt, /sys come in read-only for system tools. /dev and /proc are mounted for device and process access. /tmp and /run come in as fresh tmpfs. GPUs auto-detected (/dev/nvidia*, /dev/dri). Docker socket, X11/Wayland, /dev/shm, all auto-detected and mounted if they exist.

The most important part is how the home directory is handled. $HOME is mounted as an empty tmpfs. Then, selectively, dotfiles get layered on top. .gnupg, .aws, .ssh, .mozilla, .sparrow are never mounted (sensitive data). .claude, .crush, .codex, .aider, .config, .cargo, .cache, .docker come in as read-write because the agents need to write here. Everything else comes in read-only. Inside ~/.config, browser subdirectories are hidden behind tmpfs: BraveSoftware, Bitwarden. Same in ~/.cache: BraveSoftware, chromium, spotify, nvidia. The agent can’t even see those directories exist.

The current project directory is the only place with write permission (besides the tool dotdirs). The agent modifies the code, but doesn’t touch anything else.

macOS: sandbox-exec

On macOS, the backend is sandbox-exec with SBPL (Sandbox Profile Language) profiles. It’s a legacy Apple API, officially deprecated but with no public replacement. It works today, but Apple may remove it in the future.

ai-jail generates an SBPL profile at runtime that mirrors the same logic as Linux:

• Default deny on everything
• Allows process operations (exec, fork, signal)
• Allows network (except in lockdown)
• Allows global reads, denies sensitive paths (.gnupg, .aws, .ssh, ~/Library/Keychains, ~/Library/Mail)
• Allows writes only in the project directory, tool dotfiles, and /tmp

The limitations are real. GPU (Metal) and Display (Cocoa) are system-level on macOS, sandbox-exec can’t restrict them. The --no-gpu and --no-display flags simply have no effect on macOS. Cross-platform parity is approximate, not exact.

Even with those limitations, it’s better than running the agent completely open. sandbox-exec protects against access to sensitive filesystem areas and, in lockdown, removes write and network permissions.

Windows: Not Supported (And Probably Never Will Be)

It’s not for lack of interest, it’s lack of primitives. Windows has no userspace equivalent to Linux namespaces. No mount API like bubblewrap. AppContainers exist but use a completely different security model, require admin privileges, and mapping bwrap functionality to AppContainers would effectively mean writing another project from scratch.

The Windows answer is WSL 2:

# Inside WSL 2 (real Linux kernel)
sudo apt install bubblewrap
cargo install ai-jail
# or: mise use -g ubi:akitaonrails/ai-jail

cd /mnt/c/Users/you/Projects/my-app
ai-jail claude

WSL 2 runs an actual Linux kernel. Bubblewrap works normally. Windows files are accessible at /mnt/c/. I/O performance is slower across the 9p mount, but it works. For large projects, cloning inside ~/Projects/ on the Linux side improves performance considerably.

Lockdown Mode

For workloads you really don’t trust, there’s --lockdown:

ai-jail --lockdown bash

Lockdown does everything normal mode does, but goes further. The project gets mounted read-only (not read-write). GPU, Docker, Display and mise are disabled. --rw-map and --map flags are ignored. $HOME becomes pure tmpfs, no host dotfiles. On Linux, the network is cut with --unshare-net and the environment is wiped with --clearenv. On macOS, environment variables are wiped and write and network rules are removed from the SBPL.

It’s the most restrictive sandbox you can build short of using a VM. Useful for auditing third-party code or running agents on projects you don’t know.

Bootstrap: Automatic Permission Configuration

ai-jail --bootstrap generates permission configurations for the tools you use:

ai-jail --bootstrap

For Claude Code, it generates ~/.claude/settings.json with allow/deny/ask lists. Allows git status, diff, log, ls, grep, cargo, npm, python, docker compose. Blocks rm -rf, sudo, chmod 777, git push –force. Asks before git push, rm, docker run.

For Codex, it generates ~/.codex/config.toml with approval_policy = "on-request".

For OpenCode, it generates ~/.config/opencode/opencode.json with bash, edit, write permissions.

Before overwriting any file, it makes an automatic backup (settings.json.bak). And it rejects operations if the target is a symlink, to avoid path traversal.

It’s exactly the content I put in manually in the previous post, but automated and tested.

But Claude Code Already Has Its Own Sandbox

It does. Since October 2025, Claude Code has offered a runtime sandbox via the /sandbox command. And guess what it uses underneath? Bubblewrap on Linux and sandbox-exec on macOS. The same stack.

But the differences matter.

ai-jail is tool-agnostic. It works with Claude, Codex, OpenCode, Crush, and any command. Claude’s sandbox only protects Claude. If tomorrow you switch agents, ai-jail keeps working the same.

The thing that bothers me most is the escape hatch. When a command fails because of a sandbox restriction, Claude can retry with dangerouslyDisableSandbox, falling back to the normal permission flow. You can disable that ("allowUnsandboxedCommands": false), but it’s opt-out, not opt-in. In ai-jail, there is no escape hatch. The process runs inside bwrap or sandbox-exec, period. There’s no way for the agent to decide on its own to leave the sandbox.

Another practical difference: .ai-jail lives in the project directory and can be committed to the repo. Any dev who clones the project inherits the same sandbox policy. Claude’s sandbox depends on a global settings.json.

When run inside Docker, Claude’s sandbox falls back to an enableWeakerNestedSandbox mode that, in the words of its own documentation, “considerably weakens security”. ai-jail wasn’t designed to run inside Docker (it runs directly on the dev’s workstation), so this problem doesn’t exist.

About the network: Claude’s sandbox routes traffic through a proxy and allows/blocks by domain. ai-jail in normal mode inherits the host network; in lockdown, it cuts the entire network with --unshare-net. Claude’s approach is more granular; ai-jail’s is simpler and harder to circumvent.

The two aren’t mutually exclusive. You can run Claude’s sandbox inside ai-jail. ai-jail handles filesystem isolation; Claude’s sandbox adds per-domain network filtering. Security layers stack.

Why Not Use –dangerously-skip-permissions Without a Jail

I’ll be blunt: if you run Claude Code with --dangerously-skip-permissions without any sandbox, you’re trusting blindly that the LLM will never execute anything destructive. And you’re trusting that none of your project’s dependencies has been compromised in a supply-chain attack.

Every --dangerously flag has that name for a reason. Claude Code is explicit: that mode exists for CI/CD and automation in environments that are already isolated (containers, throwaway VMs). Not for your personal workstation with ~/.aws/credentials, ~/.gnupg/, SSH keys, and your browser’s password vault.

With ai-jail, the agent has total autonomy inside the sandbox. It does whatever it wants in the project directory, uses the tools it needs, and can’t access anything outside what was explicitly permitted.

ai-jail + Git: The Safety Net You Already Have

There’s something I haven’t mentioned yet that changes the risk calculus: if your project is in a Git repo, with a remote on GitHub/GitLab, and the agent doesn’t have permission to git push, the damage it can cause is limited to the local directory.

Think about it. The worst-case scenario inside ai-jail is the agent corrupting every file in the project. Annoying? Sure. Catastrophic? No. You run git checkout . and you’re back to the last commit. If it corrupts .git somehow (unlikely, but possible), you delete the directory and clone again. The remote was never touched.

That’s why ai-jail’s --bootstrap puts git push on the “ask” list (ask before running), not the “allow” list. And git push --force goes straight to “deny”. The agent can commit locally all it wants, can create branches, can rebase. None of that affects the remote. When it comes time to push, you review what it did and decide whether it goes live.

That combination, sandbox for the filesystem + Git for the code + manual push, already gives you a very reasonable security level for daily use. ai-jail protects your personal data and the system. Git protects your code. And the decision to publish stays yours.

If you want to go further, the next two sections cover additional layers.

ai-jail vs Dev Containers

Since I wrote ai-jail, the most frequent question is: “why not use Dev Containers?”. The short answer is that one doesn’t replace the other. They solve different problems.

Dev Containers (the containers.dev spec) define a complete development environment in a devcontainer.json. You specify base image, tools, VS Code extensions, environment variables, and the editor mounts everything for you in a Docker container. Docker also recently launched Docker Sandboxes, which go further and run each agent in a microVM with Firecracker, with hardware isolation.

ai-jail does none of that. It doesn’t define an environment. It doesn’t install tools. It doesn’t run a Docker image. It takes the environment that already exists on your machine and restricts what the process can access.

In practice, the difference is:

Dev Container makes more sense when you need the whole team to have exactly the same environment, or when the project has dependencies nobody wants to install on the host, or for running non-interactive agents in CI/CD. Docker Sandboxes with microVM are the strongest isolation that exists outside a dedicated VM.

ai-jail makes more sense when you already have the environment configured and want instant startup with no Docker daemon. Or when you use tools that are annoying to run inside a container (CUDA, Wayland, mise). Or simply when you want the same protection for any agent, not just the ones with devcontainer integration.

And you can combine them. I know people who run ai-jail inside a Dev Container to get environment reproducibility + filesystem restriction. Security layers stack.

Immutable Operating Systems: The Last Layer

If you want to take security seriously, the third layer is the operating system itself.

Immutable systems like Fedora Silverblue, NixOS, and openSUSE Aeon have a read-only root filesystem. The base system can’t be modified by any process, even with root. Updates are atomic: they either apply completely or not at all. And if something goes wrong, you roll back to the previous image in one reboot.

In practice, that means even if an AI agent escaped the sandbox (exploiting a kernel vulnerability, for example), it couldn’t modify the system persistently. On the next reboot, the system returns to the declared state. On NixOS, the entire system is defined by a configuration file (configuration.nix). On Silverblue, the base is an OSTree image that gets atomic updates via rpm-ostree.

For developers, the catch is: your dev tools run in containers (Toolbox/Distrobox on Silverblue, nix-shell on NixOS). The base system stays untouched. Desktop apps come via Flatpak, which already runs in a sandbox. The result is that the host’s attack surface is minimal.

Fedora Silverblue is probably the most accessible entry point. It’s already Fedora underneath, with GNOME, works with hardware Fedora supports, and Toolbox gives you a containerized Fedora Server where you install whatever you want without touching the host. NixOS is more powerful (full reproducibility, declarative rollback), but the learning curve is real.

The full combination looks like this: the immutable OS handles the system (read-only filesystem, atomic updates, one-reboot rollback). ai-jail handles the session (isolated namespace, ephemeral home, sensitive data invisible). And Git handles the code (remote untouched as long as the agent doesn’t have push).

None of those layers is perfect on its own. But the attack that punches through all three at the same time — escaping the namespace, persisting on a read-only filesystem, and corrupting a Git remote — is a scenario I’d be comfortable calling unlikely.

The best part is that none of them requires changing how you work. ai-jail is one command before your agent. Git you already use. And an immutable OS is an installation, not a workflow change.

Technical Details (For Those Who Care)

Written in Rust with 124 tests and 4 dependencies: lexopt (CLI parsing without clap), serde + toml (config), nix (Unix syscalls). No async runtime, no color framework (raw ANSI), ~880KB binary with LTO and strip.

Signal handling is done correctly: SIGINT, SIGTERM, and SIGHUP are forwarded to the child process. The handler only calls libc::kill, which is async-signal-safe. Process reaping uses waitpid in a loop with retry on EINTR.

Temporary files (like the custom /etc/hosts the sandbox mounts) use RAII: a SandboxGuard that implements Drop in Rust. If the parent process dies for any reason, cleanup happens.

Configuration compatibility is guaranteed by development policy: never remove fields, never rename, new fields always with #[serde(default)], unknown fields are silently ignored. Regression tests for old .ai-jail formats guarantee that updating the binary never breaks existing configs. There are 32 tests just for config.

Roadmap

What’s left:

• More tool backends in bootstrap: Aider, Cursor, Windsurf. As more agents standardize permission configuration files.
• Profile sharing for monorepos, so you don’t have to configure each service separately.

Installation and First Use (Quick Recap)

# 1. Install
brew tap akitaonrails/tap && brew install ai-jail
# or: cargo install ai-jail

# 2. On Linux, install bubblewrap
sudo pacman -S bubblewrap  # Arch
# sudo apt install bubblewrap  # Debian/Ubuntu

# 3. Enter the project and run
cd ~/Projects/my-app
ai-jail claude

# 4. (Optional) Generate permission configs
ai-jail --bootstrap

# 5. (Optional) See what the sandbox does
ai-jail --dry-run --verbose claude

The .ai-jail file it creates can be committed to your repo. From then on, any dev who clones the project runs ai-jail claude and gets the same sandbox.

Conclusion

January’s shell script solved the problem. ai-jail solves the problem properly. Per-project config, macOS support, lockdown mode, permission bootstrap, dry-run for auditing, and an 880KB binary that installs in 10 seconds.

If you use AI agents to code, run them in a sandbox. The LLM’s good intentions are no guarantee of anything, and supply-chain attacks don’t pick their victims. Process isolation is the barrier that works.

The project is GPL-3.0 and is on GitHub: github.com/akitaonrails/ai-jail

Issues and PRs are welcome.

The thing is, to be useful these tools need access to your filesystem so they can poke around your project files and analyze your code. And more: they need to run things like compilers, linters, and the everyday stuff like grep, sed, awk, ls, and other system commands.

Eventually, an LLM might fire off some random rm -rf / and start wiping things from your system, for example. The code itself, if it accidentally deletes something it shouldn’t, in theory you should be safe because your code should at the bare minimum be in a Git repo (GitHub, GitLab, etc.), so you’d just revert the change. But if the agent runs an rm outside your project directory, you can be in for all kinds of trouble.

It doesn’t happen often and all these tools have checks for it, including asking whether you really want to run a command. At the same time, they also have an option to let any command run during the session without asking — because at some point it gets tedious to “ok” every individual command. Everyone eventually gets lazy and says “screw it, run whatever you want”.

And you might be thinking “oh, my favorite tool is well-behaved, it always asks before running anything, so I’m in control”. Don’t forget: SUPPLY-CHAIN ATTACKS exist. Every other day some open source library gets compromised with malware and the programs that depend on those libs end up infected without anyone noticing. This has happened many times, in many NPM libraries for example. There’s no way to guarantee that even open source software is trustworthy. Always assume everything is insecure until proven otherwise, and treat these programs accordingly: with maximum restrictions.

To make sure these agents really aren’t going to do anything outside the project directory, the best option is to build a JAIL. Here’s the command for that:

bwrap --ro-bind /usr /usr \
      --ro-bind /bin /bin \
      --ro-bind /lib /lib \
      --ro-bind /lib64 /lib64 \
      --dev /dev \
      --proc /proc \
      --bind $(pwd) $(pwd) \
      --chdir $(pwd) \
      --unshare-all \
      --share-net \
      bash

bwrap is Bubblewrap, one of the components that make things like Flatpak possible. It creates a sandbox. The Bash that fires up when you run the command above is essentially in “jail” — locked in. Inside it we hand out read-only access to a few system directories in case it needs libraries and tools. That’s what --ro-bind is for.

But only the current directory pwd has write permission. Any command that runs inside the jail has no permission to write anywhere else on your system. Look at the example in the screenshot below where I try to delete a file in my $HOME:

It can’t even list the files in my home directory. Everything is invisible inside the sandbox. This is one of the upsides of apps running under Flatpak: they’re much more isolated than apps installed directly.

Inside this sandboxed bash we can now run opencode, crush, cursor or any other agent and be confident that they aren’t going to do anything stupid to your system.

To make life easier, I’d recommend creating a script like ~/.local/bin/ai-jail:

#!/bin/bash

# ai-jail — bubblewrap sandbox for AI coding agents
# Mounts the project dir read-write, auto-discovers home dotfiles with a
# deny-list for sensitive dirs, and isolates namespaces.
#
# Usage: ai-jail [--map PATH]... COMMAND [ARGS...]
#        ai-jail claude
#        ai-jail bash

PROJECT_DIR=$(pwd)
TEMP_HOSTS=$(mktemp /tmp/bwrap-hosts.XXXXXX)

trap 'rm -f "$TEMP_HOSTS"' EXIT

# ── Mise discovery ─────────────────────────────────────────────
REAL_MISE_BIN=$(type -p mise 2>/dev/null || echo "")

# ── Localhost fix (Go resolver needs /etc/hosts) ───────────────
printf '127.0.0.1 localhost ai-sandbox\n::1       localhost ai-sandbox\n' > "$TEMP_HOSTS"

# ── Parse --map / --rw-map arguments ─────────────────────────
EXTRA_MOUNTS=()
while [[ "${1:-}" == --map || "${1:-}" == --rw-map ]]; do
    FLAG="$1"
    MAP_PATH="$2"
    if [ -e "$MAP_PATH" ]; then
        if [[ "$FLAG" == "--rw-map" ]]; then
            EXTRA_MOUNTS+=("--bind" "$MAP_PATH" "$MAP_PATH")
        else
            EXTRA_MOUNTS+=("--ro-bind" "$MAP_PATH" "$MAP_PATH")
        fi
    else
        echo "Warning: Path $MAP_PATH not found, skipping." >&2
    fi
    shift 2
done

# ── Mise init command ──────────────────────────────────────────
if [ -n "$REAL_MISE_BIN" ]; then
    MISE_INIT="$REAL_MISE_BIN trust && eval \"\$($REAL_MISE_BIN activate bash)\" && eval \"\$($REAL_MISE_BIN env)\""
else
    MISE_INIT="true"
fi

# ── Dotfile deny-list (never mounted — sensitive data) ─────────
DOTDIR_DENY=(.gnupg .aws .mozilla .basilisk-dev .sparrow)

# Subdirs of ~/.config to hide (tmpfs over rw config mount)
CONFIG_DENY=(BraveSoftware Bitwarden)

# Subdirs of ~/.cache to hide (sensitive browser/app caches)
CACHE_DENY=(BraveSoftware basilisk-dev chromium spotify nvidia mesa_shader_cache)

# Dotdirs requiring read-write access
DOTDIR_RW=(.claude .crush .codex .aider .config .cargo .cache .docker)

# ── Helper functions ───────────────────────────────────────────
is_denied() {
    local name="$1"
    for d in "${DOTDIR_DENY[@]}"; do [[ "$name" == "$d" ]] && return 0; done
    return 1
}

is_rw() {
    local name="$1"
    for d in "${DOTDIR_RW[@]}"; do [[ "$name" == "$d" ]] && return 0; done
    return 1
}

# ── Auto-discover dot-directories in $HOME ─────────────────────
# Only directories — regular dotfiles (e.g. .claude.json) are NOT mounted.
# The tmpfs $HOME is writable so tools can create dotfiles as needed.
DOTFILE_MOUNTS=()
for entry in "$HOME"/.*; do
    [ -d "$entry" ] || continue
    name=$(basename "$entry")
    [[ "$name" == "." || "$name" == ".." ]] && continue
    is_denied "$name" && continue

    if is_rw "$name"; then
        DOTFILE_MOUNTS+=("--bind" "$entry" "$HOME/$name")
    else
        DOTFILE_MOUNTS+=("--ro-bind" "$entry" "$HOME/$name")
    fi
done

# ── Explicit dotfile mounts (regular files) ────────────────────
[ -f "$HOME/.gitconfig" ] && DOTFILE_MOUNTS+=("--ro-bind" "$HOME/.gitconfig" "$HOME/.gitconfig")
[ -f "$HOME/.claude.json" ] && DOTFILE_MOUNTS+=("--bind" "$HOME/.claude.json" "$HOME/.claude.json")

# ── Hide sensitive subdirs inside ~/.config (after rw mount) ───
CONFIG_HIDE_MOUNTS=()
for denied in "${CONFIG_DENY[@]}"; do
    [ -d "$HOME/.config/$denied" ] && CONFIG_HIDE_MOUNTS+=("--tmpfs" "$HOME/.config/$denied")
done

# ── Hide sensitive subdirs inside ~/.cache (after rw mount) ──
CACHE_HIDE_MOUNTS=()
for denied in "${CACHE_DENY[@]}"; do
    [ -d "$HOME/.cache/$denied" ] && CACHE_HIDE_MOUNTS+=("--tmpfs" "$HOME/.cache/$denied")
done

# ── Override ~/.local subdirs as rw (parent .local is ro) ──────
LOCAL_OVERRIDES=()
[ -d "$HOME/.local/state" ] && LOCAL_OVERRIDES+=("--bind" "$HOME/.local/state" "$HOME/.local/state")
for rw_share in zoxide crush opencode atuin mise yarn flutter kotlin NuGet pipx ruby-advisory-db uv; do
    [ -d "$HOME/.local/share/$rw_share" ] && LOCAL_OVERRIDES+=("--bind" "$HOME/.local/share/$rw_share" "$HOME/.local/share/$rw_share")
done

# ── GPU device mounts (NVIDIA + DRM) ─────────────────────────
GPU_MOUNTS=()
for dev in /dev/nvidia* /dev/dri; do
    [ -e "$dev" ] && GPU_MOUNTS+=("--dev-bind" "$dev" "$dev")
done

# ── Docker socket ────────────────────────────────────────────
DOCKER_MOUNT=()
[ -S /var/run/docker.sock ] && DOCKER_MOUNT+=("--bind" "/var/run/docker.sock" "/var/run/docker.sock")

# ── Shared memory (Chromium needs large /dev/shm) ───────────
SHM_MOUNT=()
[ -d /dev/shm ] && SHM_MOUNT+=("--dev-bind" "/dev/shm" "/dev/shm")

# ── Display passthrough (X11 + Wayland) ─────────────────────
DISPLAY_MOUNTS=()
DISPLAY_ENV=()

# X11 / XWayland socket
[ -d /tmp/.X11-unix ] && DISPLAY_MOUNTS+=("--bind" "/tmp/.X11-unix" "/tmp/.X11-unix")
[ -n "${DISPLAY:-}" ] && DISPLAY_ENV+=("--setenv" "DISPLAY" "$DISPLAY")
[ -n "${XAUTHORITY:-}" ] && {
    DISPLAY_MOUNTS+=("--ro-bind" "$XAUTHORITY" "$XAUTHORITY")
    DISPLAY_ENV+=("--setenv" "XAUTHORITY" "$XAUTHORITY")
}

# Wayland socket (lives in XDG_RUNTIME_DIR, typically /run/user/UID)
if [ -n "${XDG_RUNTIME_DIR:-}" ] && [ -d "$XDG_RUNTIME_DIR" ]; then
    DISPLAY_MOUNTS+=("--bind" "$XDG_RUNTIME_DIR" "$XDG_RUNTIME_DIR")
    DISPLAY_ENV+=("--setenv" "XDG_RUNTIME_DIR" "$XDG_RUNTIME_DIR")
    [ -n "${WAYLAND_DISPLAY:-}" ] && DISPLAY_ENV+=("--setenv" "WAYLAND_DISPLAY" "$WAYLAND_DISPLAY")
fi

# ── Assemble and launch ───────────────────────────────────────
echo "Jail Active: $PROJECT_DIR"

bwrap \
  --ro-bind /usr /usr \
  --symlink usr/bin /bin \
  --symlink usr/lib /lib \
  --symlink usr/lib /lib64 \
  --ro-bind /etc /etc \
  --ro-bind "$TEMP_HOSTS" /etc/hosts \
  --ro-bind /opt /opt \
  --ro-bind /sys /sys \
  --dev /dev \
  "${GPU_MOUNTS[@]}" \
  "${SHM_MOUNT[@]}" \
  --proc /proc \
  --tmpfs /tmp \
  --tmpfs /run \
  "${DOCKER_MOUNT[@]}" \
  "${DISPLAY_MOUNTS[@]}" \
  --tmpfs "$HOME" \
  "${DOTFILE_MOUNTS[@]}" \
  "${CONFIG_HIDE_MOUNTS[@]}" \
  "${CACHE_HIDE_MOUNTS[@]}" \
  "${LOCAL_OVERRIDES[@]}" \
  "${EXTRA_MOUNTS[@]}" \
  --bind "$PROJECT_DIR" "$PROJECT_DIR" \
  --chdir "$PROJECT_DIR" \
  --die-with-parent \
  --unshare-pid \
  --unshare-uts \
  --unshare-ipc \
  --hostname "ai-sandbox" \
  "${DISPLAY_ENV[@]}" \
  --setenv PS1 "(jail) \w \$ " \
  --setenv _ZO_DOCTOR 0 \
  bash -c "$MISE_INIT && ${*:-bash}"

This version is heavily customized. Read it through carefully because it has a deny-list so that only the directories you actually need inside the Jail are available. Some are read-write because Claude needs to be able to write to ~/.claude or Codex needs ~/.codex; several directories should never be inside the Jail like a Brave password store or BitWarden. Everything else you might need should be read-only. This script handles all of that.

Just chmod +x ~/.local/bin/ai-jail. Now you can run it directly or pass the command you want to run inside the sandbox:

~/.local/bin/ai-jail crush

In this version it’ll create a temporary $HOME directory in case it needs to write something temporary there. And I also set it up to map your ~/.config so the agents have access to your settings. If you need more stuff like environment variables and the like, modify it to map those too — but this is the bare minimum to put together a safe sandbox.

Be very careful with programs that run random commands on your system. Nothing is 100% safe, especially an LLM that can hallucinate at any moment and decide to delete things, or shady tools you downloaded without being sure of where they came from that might be malware in disguise. Always run truly suspicious things only in a VM, or at the very least, inside a jail like this one.

This isn’t just for AI agents, obviously. Any time you’re about to run any command you’re not sure about or that looks fishy, run it inside this jail.

As a bonus, note that I also map Mise into the container. If you’re on Omarchy, you should be using Mise too.

Specifically for Claude Code, which is what I use the most, I don’t like to leave everything authorized in automatic mode with --allow-dangerously-skip-permissions, but I also don’t like having to keep authorizing dumb stuff like every single domain it wants to search the web for (just searching is no problem at all) or any command that just lists things like ls or grep. So you can improve things by configuring directly in ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(git checkout *)",
      "Bash(git switch *)",
      "Bash(git stash *)",
      "Bash(git show *)",
      "Bash(git fetch *)",
      "Bash(git pull *)",
      "Bash(git merge *)",
      "Bash(git tag *)",
      "Bash(git remote -v*)",
      "Bash(git rev-parse *)",
      "Bash(git ls-files *)",
      "Bash(ls *)",
      "Bash(find *)",
      "Bash(grep *)",
      "Bash(wc *)",
      "Bash(cat *)",
      "Bash(head *)",
      "Bash(tail *)",
      "Bash(file *)",
      "Bash(which *)",
      "Bash(echo *)",
      "Bash(pwd)",
      "Bash(cd *)",
      "Bash(ps *)",
      "Bash(env *)",
      "Bash(printenv *)",
      "Bash(mkdir *)",
      "Bash(cp *)",
      "Bash(mv *)",
      "Bash(touch *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(yarn *)",
      "Bash(pnpm *)",
      "Bash(bun *)",
      "Bash(node *)",
      "Bash(ruby *)",
      "Bash(bundle *)",
      "Bash(rails *)",
      "Bash(rake *)",
      "Bash(go *)",
      "Bash(cargo *)",
      "Bash(rustc *)",
      "Bash(python *)",
      "Bash(pip *)",
      "Bash(docker compose *)",
      "Bash(docker ps *)",
      "Bash(docker logs *)",
      "Bash(docker images *)",
      "Bash(make *)",
      "Bash(gh *)",
      "Bash(curl *)",
      "Bash(jq *)",
      "Bash(sed *)",
      "Bash(awk *)",
      "Bash(sort *)",
      "Bash(uniq *)",
      "Bash(diff *)",
      "Bash(* --version)",
      "Bash(* --help)",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(rm -r *)",
      "Bash(sudo *)",
      "Bash(chmod 777 *)",
      "Bash(git reset --hard *)",
      "Bash(git clean *)",
      "Bash(git push --force *)",
      "Bash(git push -f *)",
      "Bash(docker rm *)",
      "Bash(docker rmi *)",
      "Bash(docker system prune *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(git rebase *)",
      "Bash(git branch -D *)",
      "Bash(git branch -d *)",
      "Bash(rm *)",
      "Bash(kamal *)",
      "Bash(docker run *)",
      "Bash(docker exec *)",
      "Bash(docker stop *)"
    ],
    "defaultMode": "acceptEdits"
  },
  "enabledPlugins": {
    "gopls-lsp@claude-plugins-official": true,
    "typescript-lsp@claude-plugins-official": true,
    "pyright-lsp@claude-plugins-official": true,
    "rust-analyzer-lsp@claude-plugins-official": true,
    "github@claude-plugins-official": true,
    "pr-review-toolkit@claude-plugins-official": true,
    "frontend-design@claude-plugins-official": true
  },
  "alwaysThinkingEnabled": true
}

Look up the documentation (or just ask Claude itself) about more customizations you can do in this file to better fit your project type or workflow.

This is basically how a Docker or Podman container works too. I explained that in my video about Docker. If you haven’t watched it yet, I recommend it.