DEV Community: Yuji Suzuki

The isolation tech behind managed AI sandboxes (gVisor, Firecracker) — worth it locally?

Yuji Suzuki — Sun, 30 Aug 2026 15:00:00 +0000

In Part 1, I laid out three options for where to draw the isolation boundary around an AI coding agent: Claude Code Sandbox, Docker AI Sandboxes, and AI Sandbox + HostMCP (this project). All three run on a normal dev machine with nothing more exotic than Docker or OS-level primitives.

But if you look at how managed cloud AI agent services isolate their sandboxes, a different pair of names comes up: gVisor and Firecracker. They're worth understanding on their own terms — and worth asking whether they belong in a local setup too.

Isolation technology proper: gVisor and Firecracker

Managed cloud AI agent services that need strong isolation actually use technologies like these:

AWS Bedrock AgentCore Code Interpreter: a "one-session-one-microVM" model, spinning up a dedicated Firecracker microVM per session (AWS docs)
Google Cloud GKE Agent Sandbox: strong kernel-level isolation via gVisor (Google Cloud docs)

Worth flagging: both of the AWS/Google services above are managed cloud services, not alternatives for a local dev environment. I'm citing them only to show that gVisor/Firecracker are real technologies actually used in production — not to run the same product-level feature comparison I did for Docker AI Sandboxes in Part 1 (they're not in the same product category to begin with).

Firecracker works by spinning up a single lightweight VM (a microVM) and running code inside it. gVisor works differently — it doesn't create a virtual machine at all. A userspace program called "Sentry" intercepts system calls and reimplements kernel functionality itself to achieve isolation (the process itself runs normally on the host). When Google describes it as "VM-level isolation strength," that's about the strength, not the mechanism — worth keeping straight.

Approach	Creates a VM?	Runs on
Firecracker (AWS)	Yes (microVM)	Linux (requires KVM)
gVisor (Google)	No (intercepts syscalls)	Linux (as a Docker runtime)

Using these locally

Both technologies are open source, so they're not cloud-provider-exclusive — you can use them locally too. How easy that is differs a lot between the two.

gVisor can be used locally just by switching the Docker runtime to runsc. This raises "process isolation strength" — a different axis from AI Sandbox's "secret hiding via volume mounts" covered in Part 1 — so it's additive, not a replacement. You can check whether it's actually usable in your environment with check-gvisor.sh (script on GitHub; a read-only check run on the host OS via HostMCP).

Firecracker can run locally too, but it needs Linux + KVM plus an integration layer like firecracker-containerd — switching runtimes alone isn't enough. In practice this becomes "choose an entirely different isolation boundary," putting it closer to the Docker AI Sandboxes product category from Part 1.

Whether kernel exploits need to be part of your threat model at all also depends on your dev machine's OS.

On macOS with Docker Desktop/OrbStack, it's easy to forget that containers actually run inside a separate, disposable, lightweight Linux VM — not directly on macOS itself. Even a successful kernel exploit inside a container only compromises that Linux VM directly; reaching macOS itself (the Darwin kernel) would require a separate attack on the hypervisor (a VM escape) as an additional step. In other words, on a Mac dev machine, there's already one extra layer of isolation at work — from Docker Desktop/OrbStack's own implementation — independent of anything AI Sandbox configures. So there's generally little need to add gVisor on a Mac dev machine.

On Linux with Docker running directly, a kernel exploit inside a container is a direct attack on the host OS kernel. AI Sandbox doesn't specify a runtime in docker-compose.yml, so it stays on Docker's default runc, with nothing blocking this path. So on a Linux dev machine, switching the Docker runtime to runsc (gVisor) is worth considering. As noted above, this is an additive measure on a different axis from secret hiding, and you can check feasibility the same way, with check-gvisor.sh.

Because of this difference in baseline exposure, the priority of adding gVisor-based isolation differs between Linux and Mac dev machines.

Wrapping up

gVisor and Firecracker solve a real problem — they're what production cloud services reach for when they need strong, kernel-level isolation. But for a local dev machine, whether they're worth adopting depends heavily on your OS: on Linux, runsc is a cheap, additive check worth running; on macOS, Docker Desktop/OrbStack's own VM boundary already covers most of what you'd gain. Firecracker, meanwhile, is enough of a setup lift that adopting it locally is really "pick a different isolation boundary" rather than a drop-in addition.

None of this changes the two gaps that AI Sandbox + HostMCP focuses on from Part 1 — filesystem-level secret hiding and controlled cross-container access. gVisor/Firecracker sit on the "process isolation strength" axis; AI Sandbox sits on the "does the AI's filesystem contain secrets at all" axis. They're orthogonal, and you can combine them if your setup calls for it.

If you haven't read Part 1 yet, it's here: Part 1.

https://github.com/YujiSuzuki/ai-sandbox

"Don't you trust the AI vendor's own sandbox?" I didn't have a good answer.

Yuji Suzuki — Sat, 29 Aug 2026 15:41:02 +0000

I build an open-source AI sandbox project, and when I mention it to people building products and solutions for a living, I sometimes get this reaction:

"Don't AI vendors already ship their own sandbox? Don't you trust that?"

I froze for a second. It's not that I don't trust it. It's that the layer an AI vendor's own sandbox (like Claude Code Sandbox) protects, and the layer my project protects, are simply different things.

Once you start looking into how to run AI coding agents safely, you keep running into tools with confusingly similar names: Claude Code Sandbox, Docker AI Sandboxes, Docker MCP Toolkit, firejail, gVisor, Firecracker... They all seem to point in the same direction — "isolate the AI agent" — but what they actually protect, and how they work, differ more than you'd expect. This post is my attempt to actually answer that question properly.

The short answer: they protect different layers

Here's the comparison up front, as a table.

Feature	Claude Code Sandbox	Docker AI Sandboxes	AI Sandbox + HostMCP (this project)
Execution restriction	OS-level	microVM isolation	Container isolation
File-read blocking	Deny rules (application-level)	None	Volume mounts (filesystem-level)
Multi-project scope	Limited (no parent-directory traversal)	Single workspace	Whole workspace + per-file hiding
Cross-container access	Restricted	Isolated	Controlled via HostMCP
Output secret masking	None	None	Automatic
Startup validation	None	None	Automatic sync check
Setup complexity	None needed on macOS; Linux/WSL2 needs bubblewrap + socat	Docker Desktop	Docker + docker-compose

The point isn't "which one is strongest" — it's that each tool targets a different threat model. Let's go through them one by one.

Claude Code Sandbox — restricts what Bash commands can do

Claude Code Sandbox uses OS-level primitives (Seatbelt on macOS, Bubblewrap on Linux) to restrict filesystem writes and network access. Adding a Read deny rule in the permission settings also lets you block the AI from reading specific files.

The strength here is clear: on macOS it gives you OS-level execution restriction with zero extra setup (Linux/WSL2 needs bubblewrap and socat installed). It also cuts down on permission-confirmation friction.

That said, there are two gaps that aren't covered.

First, deny rules are an application-level mechanism. They depend both on correct configuration and on the AI tool actually respecting the rule. Worse, these deny rules don't traverse parent directories. In a monorepo or multi-project workspace, that means one project's config won't protect a sibling project's secrets.

AI Sandbox sidesteps this at the file level entirely. Each project's secret files are individually hidden from the AI's filesystem via volume mounts, regardless of directory hierarchy. There's no rule to traverse in the first place — the idea is that the rule shouldn't need to exist.

Second, there's friction with Docker commands. Docker commands need direct access to the Docker socket, which is structurally incompatible with the sandboxing mechanism. In fact, Claude Code Sandbox's own troubleshooting docs recommend adding docker * to excludedCommands (i.e., excluding it from the sandbox). The result: Docker operations run with unrestricted host privileges, entirely outside the sandbox's protection.

Aside: firejail

On Linux, firejail often comes up in comparisons. It sandboxes at the process level using Linux namespaces — the same category as the bubblewrap that Claude Code Sandbox uses. Unlike this project's approach of carving out the AI agent's entire execution environment, firejail is meant to nest inside a larger sandbox.

On the narrow question of "hiding secrets," though, it's a different story. firejail's --blacklist option denies access to target paths at the OS kernel level. According to firejail's own docs, blacklisted files/directories "remain visible in the filesystem, but become completely inaccessible." I couldn't confirm from public docs whether the underlying implementation is bind-mount-based, but in the sense that it doesn't depend on the AI tool respecting a rule, it's closer in spirit to AI Sandbox's volume-mount approach than to application-level deny rules (though the AI-facing appearance may differ — AI Sandbox shows empty files/directories, which may not be exactly how firejail presents it).

That said, firejail is limited to a single process, isn't designed to treat a whole multi-project workspace as one unit, and doesn't cover controlled access to other containers. It's Linux-only, so it's not available on macOS, which is AI Sandbox's primary target. On a Linux dev machine specifically, --blacklist alone could plausibly reproduce secret-hiding on its own, but it doesn't cover the rest.

Docker AI Sandboxes — isolates everything inside a microVM

Docker AI Sandboxes runs the AI agent inside an isolated microVM with its own Docker daemon. The agent can't touch the host system at all.

The strength: strong microVM-based isolation, full autonomy for the AI agent inside the sandbox, and each sandbox gets its own Docker daemon.

There are two gaps. It syncs the entire workspace directory into the microVM, with no mechanism to exclude specific files — so .env files are plainly visible from the inside. This isn't a flaw so much as a difference in design goals: Docker AI Sandboxes exists to "protect the host from the AI agent's execution," not to "hide secrets from the AI." The other gap: because it's fully isolated, a sandbox can't talk to other containers, which rules out cross-container debugging.

Docker MCP Toolkit — focused on isolating MCP servers

Docker MCP Toolkit provides 200+ containerized MCP servers with built-in isolation and secret management. Its strengths are a rich catalog of pre-built MCP servers and built-in secret management for MCP server configuration.

But this tool is focused on isolating MCP servers — hiding project-level secrets from the AI is out of scope. It doesn't address .env files or private keys sitting in your source tree.

The two gaps AI Sandbox fills

Given the comparison so far, AI Sandbox + HostMCP can be summarized as filling two specific gaps.

Gap 1: Filesystem-level secret hiding

Instead of blocking access to secrets via rules (which can be misconfigured or bypassed), Docker volume mounts physically remove secrets from the AI's filesystem.

volumes:
  - /dev/null:/workspace/my-app/.env:ro         # appears as an empty file to the AI
tmpfs:
  - /workspace/my-app/secrets  # appears as an empty directory to the AI

Secrets don't exist in the AI's world at all. Not blocked by a rule, not filtered by a config — they're simply not there. The application container, meanwhile, mounts the real files as usual.

As a safeguard against misconfiguration, the sandbox runs a validation check at startup to confirm the AI tool's deny rules stay in sync with the volume mounts in docker-compose.yml. If a secret file is only configured on one side, a warning fires before the AI can access it. A separate check also scans for secret-looking files that aren't hidden in docker-compose.yml, every time an AI session starts. This catches configuration gaps early for files created mid-development, and the AI itself asks the user how to handle a flagged file — whether it actually needs hiding or is fine to leave as-is.

Gap 2: Controlled cross-container access

HostMCP acts as a gateway between AI Sandbox and Docker containers, enforcing a security policy. The AI can read logs, run whitelisted commands, and inspect containers — but can't access blocked paths or run arbitrary commands. Starting/stopping containers is disabled by default and only works if explicitly enabled in config. Sensitive data (passwords, API keys, tokens) is automatically masked in output, and HostMCP itself binds only to loopback (127.0.0.1) by default, so it's not reachable from other machines on the network out of the box.

Layering these tools together

So far this has been framed as "versus," but in practice these tools sort into two layers with different properties, and thinking of it that way clarifies where each one fits.

Isolation boundary: something you choose based on your threat model

Docker AI Sandboxes and AI Sandbox both answer the question "where do you draw the line around the AI agent's entire execution environment?" The former uses a microVM; the latter uses containers plus volume-mount-based secret removal. Since their roles overlap, they're not meant to be stacked — you pick one based on your threat model.

Claude Code Sandbox targets something different — it only restricts Bash command execution at the OS level — so it can be nested inside whichever outer environment you chose. That said, when nesting inside an unprivileged container like AI Sandbox, bubblewrap can fail to mount a fresh /proc, per the official docs, requiring enableWeakerNestedSandbox — in which case the nested sandbox's process-space isolation ends up depending on the outer container boundary instead (the permission deny rules themselves are unaffected and keep working). So it's not quite true that "nesting inside AI Sandbox gets you maximum protection" — there's an added benefit, but it's limited.

Isolation boundary option	Role
Claude Code Sandbox	Restricts Bash command execution at the OS level (nestable inside other boundaries, with the caveat above)
Docker AI Sandboxes	Isolates the whole AI agent in a microVM
AI Sandbox (this project)	Container isolation + volume mounts to remove secrets from the AI's filesystem

If you're curious how these boundaries relate to the kernel-level isolation tech (gVisor, Firecracker) that managed cloud AI services use, and whether it's worth adopting locally, I cover that in Part 2 — it's a tangent from AI Sandbox's own scope, so I split it out to keep this post focused.

Permission layer: usable independently, alongside anything above

HostMCP's cross-container access control and Managed Settings' deny rules sit at a different layer from the isolation boundary. They control access at the level of individual tool calls, so they can be layered independently on top of whichever isolation boundary you pick above.

Wrapping up

"How should you isolate an AI agent?" doesn't have a single right answer. Claude Code Sandbox restricts command execution, Docker AI Sandboxes isolates everything inside a microVM, and gVisor/Firecracker are used in production as even stronger isolation technologies in the cloud. Each protects a different layer, against a different threat model.

What AI Sandbox + HostMCP chose to focus on is: physically erasing secrets at the filesystem level, and safely bridging cross-container access behind an approval flow. It's built specifically to fill those two gaps, and designed to be additive — not in competition with the other isolation boundaries or permission layers above.

Safe AI-driven development needs both: protecting secrets, and not getting in the way of the humans and AI actually doing the work. AI Sandbox is built to try to hold both of those at once.

If you've ever looked at your own dev setup and thought "wait, is the AI reading my private keys too?" — take a look at the repo.

https://github.com/YujiSuzuki/ai-sandbox

One Repo Became Three — Quietly, Then Publicl

Yuji Suzuki — Tue, 28 Jul 2026 16:56:47 +0000

One Repo Became Three — Quietly, Then Publicly

ai #docker #security #mcp

Previously

Back in February, I published AI Sandbox Environment + DockMCP — a single repo that isolated AI coding agents in a Docker container, hid .env files and secrets at the filesystem level, and gave AI a controlled path back out to other containers through an MCP server.

Structurally, though, it was three different jobs wearing one trench coat: a devcontainer template, a host-side MCP server, and an in-container script/tool discovery server. I said I'd eventually split them apart. What I didn't say at the time was what I was about to use the split version for.

The Quiet Part

Before any of this was public, I split ai-sandbox-dkmcp into three repos privately and used that setup to build and ship an actual product: Tokeruyo, an iOS app.

Building a real iOS app inside the sandbox — not a demo, not the SecureNote sample app — surfaced friction that a template alone never would have. Xcode builds and tests don't run inside a Linux container; they need the host OS. That meant the host-tools mechanism, which had been a minor feature for wrapping docker-compose up, suddenly had to carry real weight:

xcode-build.sh, xcode-test.sh, xcode-archive.sh — host tools that let AI kick off Xcode operations without leaving the sandbox
A per-tool timeout declaration (# @timeout: 600 in a script's header). The global timeout was 60 seconds, fine for something like docker-compose up — and xcode-test.sh blew right through it. The fix wasn't obvious on the first try; it took some back-and-forth with Claude Code, weighing "just raise the global default" against "let a tool declare its own ceiling," before landing on the per-tool declaration (still clamped by an admin-controlled max, so a script can't unilaterally claim an hour).
Generic docker-compose-up.sh / -down.sh / -build.sh wrappers, once one-off demo scripts, made reusable

None of this was designed up front. It's the residue of actually depending on the tool to ship something, not just to demo it. If you look at docs/host-access.md in the ai-sandbox repo today, the Xcode tools and the @timeout mechanism are still sitting there — leftovers from that period, kept because they turned out to be generally useful.

The app shipped. That felt like a natural stopping point.

The Public Part

With the app out, I published the three-way split for real:

Repo	What it is	Runs where
ai-sandbox	The devcontainer template — secret hiding, project structure, slash commands	Docker (VS Code / CLI)
hostmcp	MCP server for host-side access — containers, host tools, host OS commands	Host OS
sandbox-mcp	Lightweight MCP server for script/tool discovery inside the container	Inside the container (stdio)

DockMCP became HostMCP. The bundled tool-discovery layer became SandboxMCP. What's left of the original repo is just AI Sandbox — the template.

AI Sandbox (container)
  └─ SandboxMCP (stdio)          ← discovers .sandbox/scripts/ and .sandbox/tools/
  └─ hostmcp client (via HTTP)   ← talks to HostMCP on the host OS
        ↓
Host OS: HostMCP server → API container, DB container, host tools, …

Publishing didn't stop the work, either. HostMCP picked up a proper installer (go install github.com/YujiSuzuki/hostmcp@latest), host-path masking so the home directory's username never leaks into what AI sees, a "dangerous mode" for read-only debugging commands that still respects blocked paths, and large-output handling so a runaway build log doesn't blow out the context window. SandboxMCP picked up nested-git-repo detection for multi-repo workspaces. It's settled into a steady state now, which is why this post exists.

Why Split at All

Independent installs. Someone with an existing devcontainer might want HostMCP for host access, or SandboxMCP for script discovery, without adopting the whole secret-hiding template. As one repo, that meant cloning the template and cherry-picking.

Independent release cadence. HostMCP being go install-able shouldn't be gated behind a template release. It's a HostMCP concern now, not an ai-sandbox concern.

Real usage exposes real seams. The Xcode host tools and per-tool timeouts didn't come from design — they came from hitting a wall while shipping an actual app. Having HostMCP as its own project made it obvious that "host tools" needed to support more than the couple of demo scripts it launched with.

What Didn't Change

Secrets are physically absent, not rule-blocked. .env files and private keys still don't exist in AI's filesystem — not hidden by a deny list, just not there.

AI observes, humans act on infrastructure. HostMCP still won't let AI rebuild an image or run docker-compose up directly on its own judgment; that has to go through an approved host tool, and approval is a human step.

Still just Docker + MCP. No lock-in to a specific AI tool. Claude Code, Gemini CLI, Claude Desktop via MCP — all of it works the same way it did as one repo.

Try It

Setting up a new project? Start with ai-sandbox — click "Use this template."
Already have a devcontainer and just want host access? hostmcp installs standalone.
Want AI to discover your own scripts and tools without re-explaining them every session? sandbox-mcp is a go install away.

Feedback and issues are welcome on any of the three repos.

My AI Escaped Its Container and Did Everything — Except Review Its Own Code

Yuji Suzuki — Tue, 17 Feb 2026 15:23:49 +0000

Previously: The Complete Dev Cycle

In Part 4 of this series, my AI assistant achieved something remarkable. Running inside a secure Docker container, it could now execute the entire development cycle:

Code → Test → Build → Deploy → Commit

I called it the finale. The trilogy was complete. The AI could write code, run tests, build artifacts, deploy to containers, and commit changes — all while keeping secrets safely hidden.

I was wrong. Something was missing.

The Missing Piece

Look at that cycle again. Now think about how a real development team works.

Code → Test → Build → Deploy → Commit → PR → ...

Where's the review?

In any professional team, code doesn't just flow from writing to deployment. Someone reads it. Someone checks for bugs, security issues, architectural problems. Someone asks "did you consider this edge case?"

My AI could do everything — except check its own work.

The Official Plugin

Claude Code has an official /code-review plugin. When I discovered it, I was impressed by its design:

Parallel agents: Multiple AI agents analyze code simultaneously from different angles — bug scanning, CLAUDE.md compliance checking
Confidence scoring: Each finding gets a score, filtering out noise
Verification step: A separate agent re-checks findings to eliminate false positives

This is serious engineering. Not "ask AI to review code" but a structured, multi-stage pipeline designed to produce high-signal results.

I installed it immediately.

And it didn't work.

Why It Couldn't Reach

The official plugin is designed for a standard GitHub workflow. It expects:

gh CLI — to fetch PR details from GitHub
A GitHub PR — the review target is a pull request
A single repository — it operates within one project

My AI Sandbox environment has none of that:

No gh CLI (the container has no GitHub authentication)
No PR yet (I want review before pushing, not after)
Multiple independent repositories in one workspace (API, Web, iOS — each with their own Git history)

The plugin couldn't reach my code. Not because it was poorly designed — it's excellent at what it does. But it was built for a different moment in the development cycle: after you push. I needed something before.

Learning From the Design

I couldn't use the plugin directly, but I could learn from it.

The plugins documentation showed me that Claude Code's custom commands are just Markdown files — structured instructions that become slash commands. The official /code-review demonstrated what a well-designed review pipeline looks like: parallel analysis, scoring, verification.

So I did what my AI Sandbox was built for. I asked the AI:

Analyze the code-review plugin and create a custom command that works locally. Allow selecting which project to review. Confirm the target branch with the user. Run the same kind of review, but without GitHub access.

The AI read the official plugin, understood its structure, and produced a local version. No gh dependency. Multi-project support. Git and non-Git modes.

It worked.

From One to Nine

Once the local review command was running, the next thought was obvious.

If I can have a general code reviewer, why not a security reviewer? A performance reviewer? An architecture reviewer?

Each review type needs different expertise. A security review looks for injection vulnerabilities, authentication gaps, and data exposure. A performance review looks for N+1 queries, unnecessary allocations, and missing caching. A general review catches bugs and checks CLAUDE.md compliance.

One command became nine:

Command	Purpose
`ais-local-review`	General code review (bugs, CLAUDE.md)
`ais-local-security-review`	Security vulnerabilities
`ais-local-performance-review`	Performance bottlenecks
`ais-local-architecture-review`	Structural concerns
`ais-local-test-review`	Test quality assessment
`ais-local-doc-review`	Documentation accuracy
`ais-local-prompt-review`	AI prompt/command quality
`ais-refactor`	Concrete refactoring suggestions
`ais-test-gen`	Automated test generation

All nine share the same pipeline architecture inspired by the official plugin:

Parallel Analysis → Scoring → Verification → Report
(4-5 Sonnet agents)  (Haiku)   (Sonnet)

Each specialized command sends parallel agents with different review perspectives. A scoring agent evaluates confidence. A verification agent eliminates false positives. Only high-confidence, verified findings make it to the final report.

The Pipeline in Action

Here's what happens when you run /ais-local-review:

Step 1: Select a project and branch (or files, if no Git)

Step 2: Four Sonnet agents launch in parallel:

Agent #1: CLAUDE.md compliance — does the code follow project conventions?
Agent #2: Bug scan — obvious logic errors, edge cases
Agent #3: History analysis — are we reintroducing a previously fixed bug?
Agent #4: Comment check — does the code match its own documentation?

Step 3: A Haiku agent scores every finding (0-100)

Step 4: A Sonnet verification agent re-checks anything scoring 75+

Step 5: Only confirmed, high-confidence issues appear in the report

The result is a focused report. Not a wall of nitpicks — a short list of things that actually matter.

Two Reviews, Two Moments

Here's what's interesting: the official plugin and my local commands aren't competing. They serve different moments in the development cycle.

Code → Review → Test → Build → Deploy → Commit → PR → Review
         ↑                                                ↑
    ais-* commands                              Official /code-review
    Before you push                              After you push
    Quality gate                                 Team review
    Local, private                               GitHub, collaborative

The official /code-review is for when your code is ready for team eyes. It posts comments on PRs, suggests changes, integrates with GitHub's collaboration features.

My ais-* commands are for before that moment. While you're still developing. Before you've committed, sometimes before you've even finished writing tests. A private quality gate that catches issues early, when they're cheapest to fix.

The Completed Cycle

Remember the development cycle from Part 4?

Code → Test → Build → Deploy → Commit

Here's what it looks like now:

Code → Review → Test → Build → Deploy → Commit
         ↑
    The missing piece

The AI can write code, review its own work (from multiple perspectives), run tests, build, deploy, and commit. The quality gate that was missing is now in place.

What I Learned

This project started because the official plugin couldn't reach my code. But that limitation led somewhere unexpected.

The official plugin's design — parallel agents, confidence scoring, false positive elimination — was the blueprint. Open source at its best: you read how something works, understand the principles, and adapt them to your environment.

I didn't just get a code reviewer. I got nine specialized review tools, a refactoring assistant, and an automated test generator. All because the official plugin showed me what a well-designed review pipeline looks like, and my AI Sandbox gave me a place to build one that works locally.

The Series So Far

What started as "my AI can see my API keys" has become something larger:

Secrets: Hide sensitive files from AI using Docker volume mounts
Toolbox: AI discovers and uses tools autonomously via SandboxMCP
Host Access: AI breaks out of its container with controlled host OS access
Review (this article): AI reviews its own code, completing the dev cycle

The trilogy became a tetralogy. I'll stop promising it's complete.

The AI Sandbox with DockMCP is open source: GitHub repository

If you've built custom review commands for your AI workflow, I'd love to hear about it in the comments.

My AI Broke Out of Its Container — And I Let It

Yuji Suzuki — Sun, 15 Feb 2026 15:56:36 +0000

Previously, on AI Sandbox...

If you've been following along, you know the story:

Part 1: I discovered my AI assistant was reading my API keys. I built a Docker sandbox that hides secrets via volume mounts — files appear empty to AI, but application containers still have full access.

Part 2: I gave the sandboxed AI a toolbox (SandboxMCP). It surprised me by autonomously discovering a forgotten tool and repurposing it to solve a problem I hadn't anticipated.

Now for the final chapter.

The Last Wall

After Parts 1 and 2, my AI assistant could:

✅ Read and edit all source code
✅ Check container logs via DockMCP
✅ Run tests inside containers
✅ Discover and use tools autonomously

But there was one thing it still couldn't do:

Anything that required the host OS.

"Start the demo app" → Sorry, I can't run docker-compose.
"Build the containers" → I don't have access to Docker.
"Commit this change" → I can commit, but the message style...

Every time I needed to build, deploy, or manage containers, I had to switch to my terminal and do it myself. The AI was powerful inside its box, but the box was still a box.

The Uncomfortable Question

Here's the thing about containers: they're designed to isolate. That's their entire purpose. Giving a sandboxed AI access to the host OS sounds like... undoing the sandbox.

I sat with this tension for a while. The whole point of AI Sandbox was security — hiding secrets, controlling access, preventing accidents. How do you extend reach without breaking trust?

The answer turned out to be the same pattern I'd used twice before: don't give access, give a controlled interface.

Part 1: Don't give AI your secrets → Give it DockMCP to read logs and run tests
Part 2: Don't install tools for AI → Let it discover what's available
Part 3: Don't give AI the host OS → Give it approved scripts it can run through a gateway

How Host Access Works

The architecture is straightforward:

AI Sandbox (container)
  │
  │  MCP / HTTP
  ▼
DockMCP Server (host OS)
  ├── Container access     ← existing (logs, exec, stats)
  ├── Host Tools           ← NEW: run approved scripts
  ├── Container Lifecycle  ← NEW: start/stop/restart
  └── Host Commands        ← NEW: whitelisted CLI commands

But the interesting part isn't the architecture — it's the approval workflow.

The Two-Stage Approval

AI (or developers) can propose a new host tool by placing a script in .sandbox/host-tools/:

#!/bin/bash
# demo-up.sh
# Start demo application containers
docker compose -f demo-apps/docker-compose.yml up -d

But this script cannot run yet. It's in staging — inside the workspace where AI can write files.

To activate it, the human runs dkmcp tools sync on the host:

$ dkmcp tools sync

📋 Reviewing tools from .sandbox/host-tools/:

  demo-up.sh (NEW)
    Start demo application containers
    ─────────────────────────────
    #!/bin/bash
    docker compose -f demo-apps/docker-compose.yml up -d
    ─────────────────────────────
    Approve? [y/N]: y
    ✅ Approved → ~/.dkmcp/host-tools/myproject/demo-up.sh

Only the approved copy runs. If AI modifies the staging version later, dkmcp tools sync detects the SHA256 mismatch and prompts for re-approval.

This means:

AI can propose tools (creative freedom)
Humans approve tools (security control)
Only approved versions execute (integrity guarantee)

What Changed in Practice

Before v0.5.x, a typical conversation:

Me: Start the demo app.
AI: I can't run docker-compose from inside the container. Please run this on your terminal:
docker compose -f demo-apps/docker-compose.yml up -d

After v0.5.x:

Me: Start the demo app.
AI: [calls run_host_tool with demo-up.sh]
Demo containers started. API is at :3000, Web at :3001.

The difference seems small. But multiply it across every build, every restart, every deployment — and the friction adds up. The AI went from being a helpful advisor that tells you what to type, to a capable agent that does the thing.

The Commit Workflow (A Small Thing That Matters)

One more thing that came together in this release. I built a commit message script (commit-msg.sh) that creates a collaborative workflow:

Generate draft from staged changes → Check previous commit style → Refine together → Commit

Here's what it looks like in practice:

$ .sandbox/scripts/commit-msg.sh              # Generate draft from git diff
$ .sandbox/scripts/commit-msg.sh --log        # Check how recent commits read
# ... AI and human refine CommitMsg-draft.md together ...
$ .sandbox/scripts/commit-msg.sh --msg-file CommitMsg-draft.md  # Commit

The interesting discovery: the script itself always had a --log option to check previous style, but AI wasn't using it. The fix wasn't changing the script — it was writing the full three-step workflow in the AI instruction file (CLAUDE.md). Once AI could see the steps laid out explicitly, it followed them perfectly.

If you want AI to follow a workflow, don't just give it a tool — spell out the steps. The tool can be perfectly designed, but AI won't discover optional flags on its own. This applies to any AI coding assistant, not just this project.

The Trilogy Arc

Looking back, there's a clear progression:

Phase	What AI Could Do	What It Couldn't
v0.1: Protect	Read code	See secrets
v0.3: Equip	Discover and use tools	Touch the host OS
v0.5: Unleash	Run host scripts, manage containers	(nothing that matters for daily dev)

The sandbox started as a cage. Then it became a workshop. Now it's a full development environment — with the security model still intact.

Secrets? Still hidden (volume mounts haven't changed).
Container access? Still controlled (whitelist, output masking).
Host access? Controlled too (approval workflow, SHA256 verification).

Every layer of capability was added on top of the security foundation, never at the expense of it.

Is This the End?

For the core functionality — yes. My personal development workflow is now complete:

Code → Test → Build → Deploy → Commit → Code → ...

The full loop. All within the sandbox.

AI reads and writes code (sandbox)
AI checks logs and runs tests (DockMCP container access)
AI discovers and uses tools (SandboxMCP)
AI builds, deploys, and manages containers (DockMCP host access)
AI drafts commit messages collaboratively (commit-msg.sh)

There's nothing left in my daily workflow that requires me to switch to a terminal and do things manually.

Well, except dkmcp tools sync. That one stays manual — by design.

Try It

The template is open source. You can set up the entire environment in about 10 minutes:

GitHub: ai-sandbox-dkmcp

It works with Claude Code, Gemini CLI, and any MCP-compatible AI tool. If you're running AI coding assistants and haven't thought about where your secrets go — now's a good time.

If you find it useful, a star on GitHub would mean a lot.

This is Part 3 of the AI Sandbox series. Part 1: Secrets | Part 2: Tools

I Gave My AI a Toolbox — It Surprised Me by Using It

Yuji Suzuki — Sat, 14 Feb 2026 07:41:31 +0000

A 3.5MB Go binary was sitting in my source tree, staged for commit. git log showed nothing — it had never been committed. I had no idea how it got there.

I asked Claude Code to investigate. I didn't point it to any specific tool. I didn't tell it how to search. I just said: "There's a mystery binary in the repo. Where did it come from?"

It solved the mystery in under a minute — using a tool I'd forgotten I built.

But that's getting ahead of the story.

This is Part 3 of the AI Sandbox series. Part 1 introduced the AI Sandbox and secret hiding. Part 2 positioned it against official Docker and Claude Code sandboxes. This article focuses on what happens inside the sandbox — specifically, what AI does when you give it the ability to discover tools on its own.

Drop a File, Get a Tool

Inside the AI Sandbox — a Docker-based environment where AI coding agents run in isolation — I wanted a simple way to extend what AI can do. Not by editing config files or registering MCP servers for every new capability, but something closer to a plugin folder: drop a file in, and AI can use it.

That's what SandboxMCP does. It's an MCP server that runs inside the container alongside Claude Code (or Gemini CLI), scanning two directories on demand:

.sandbox/tools/ — Go source files
.sandbox/scripts/ — Shell scripts (which can call Python, Node.js, etc.)

When AI asks "what tools are available?", SandboxMCP scans these directories, parses the header comments for descriptions and usage info, and exposes them as MCP tools. No build step, no npm install, no manual registration.

How it works

Each file just needs a header comment describing what it does. SandboxMCP parses these on demand and exposes them as MCP tools. AI discovers a tool through list_tools, reads its documentation with get_tool_info, and executes it with run_tool — all without you telling it to.

Here's the header from search-history.go — the tool that ended up solving the mystery:

// search-history.go - Claude Code conversation history search tool
//
// Usage:
//   go run .sandbox/tools/search-history.go [options] <pattern>
//
// Examples:
//   go run .sandbox/tools/search-history.go "DockMCP"
//   go run .sandbox/tools/search-history.go -role tool -tool Bash "go build"

A few lines of comments. That's all AI needs to decide whether a tool is relevant.

┌────────────────────────────────────────────────────┐
│ AI Sandbox (inside container)                      │
│                                                    │
│  ┌─────────────────┐      ┌─────────────────────┐  │
│  │ Claude Code     │ ←──→ │ SandboxMCP (stdio)  │  │
│  │                 │      │                     │  │
│  └─────────────────┘      │ • list_tools        │  │
│                           │ • get_tool_info     │  │
│  ┌─────────────────────┐  │ • run_tool          │  │
│  │ .sandbox/tools/     │  │ • list_scripts      │  │
│  │ • search-history.go │←─│ • get_script_info   │  │
│  │ • usage-report.go   │  │ • run_script        │  │
│  └─────────────────────┘  └─────────────────────┘  │
│  ┌─────────────────────┐                           │
│  │ .sandbox/scripts/   │                           │
│  │ • validate-secrets  │                           │
│  │ • sync-secrets      │                           │
│  └─────────────────────┘                           │
└────────────────────────────────────────────────────┘

Back to the Mystery Binary

So — a 3.5MB Go binary, staged but never committed. Where did it come from?

Claude Code started with the obvious: git log, file timestamps, git diff --cached. Dead ends. The binary was there, but nothing in the commit history explained it.

Then something unexpected showed up in the tool calls. Instead of asking me for more context, Claude Code called list_tools on SandboxMCP — browsing the tool catalog on its own initiative. It found search-history, read the documentation with get_tool_info, and decided the -role tool -tool Bash filter was what it needed. It ran the search across all past Claude Code sessions — not looking for conversations, but for Bash commands.

Within seconds, the culprit appeared: a session from a few days earlier where AI had run go build without the -o flag to verify that the code compiled. The build succeeded, but go build without -o drops the binary in the current directory. That's how a 3.5MB executable ended up in the source tree.

I didn't build search-history for this scenario. I wrote it for finding past conversations about specific topics. But because it was sitting in .sandbox/tools/, SandboxMCP exposed it, and Claude Code decided — on its own — that it was the right tool for the job.

The auto-discovery mechanism turned a tool I'd forgotten about into the solution for a problem I hadn't anticipated.

Discovery vs. Installation

By now, AI using tools is nothing remarkable. What caught my attention was the how.

There are already several MCP servers for searching Claude Code conversation history — claude-historian-mcp, claude-code-conversation-search-mcp, and others. They work well. If I'd installed one, Claude Code could have searched past sessions too.

But here's the thing: I would never have installed a conversation-search MCP server to debug a mystery binary. That connection — "unknown file in the repo" → "search past AI sessions for Bash commands" — only became obvious after the answer was found. Before that, it was a lateral leap that required recognizing a tool built for one purpose could solve a completely different problem.

That's the gap between installation and discovery. When you install a tool, it exists because you anticipated the need. When AI discovers tools from a catalog, it can make connections you didn't plan for — repurposing tools across problem boundaries you never drew.

You don't have to predict every need upfront. You build a toolbox, and AI reaches for the right tool when the moment comes.

Building Your Own Toolbox

The pattern scales with the tools you add. Shell scripts can call Python, Node.js, or anything else installed in the container. The only requirement is a header comment that describes what the tool does.

Some examples from this project:

Tool	What It Does	How AI Uses It
`search-history.go`	Search past Claude Code sessions	"What did we work on last week?"
`usage-report.go`	Token usage by model and period	"How much did I spend this month?"
`validate-secrets.sh`	Verify secret hiding works	"Are my secrets properly hidden?"
`sync-secrets.sh`	Sync secret config across environments	"Check if my secret config is consistent"

You can start with one tool. The cost of an unused tool sitting in a directory is zero. The value of having the right tool already there when an unexpected problem arises — that's what this article is about.

What This Doesn't Solve

To be consistent with the honesty in Part 1 and Part 2:

Tools must already exist. AI discovers tools — it doesn't create them from scratch in the moment. Someone has to write the tool and place it in the directory first. (Though in practice, AI can write a tool in one session that another session later discovers and uses.)
Discovery depends on good descriptions. If your header comment is vague, AI may not recognize the tool as relevant. The quality of the metadata matters.
Scoped to the sandbox. SandboxMCP only sees tools inside the container. It doesn't discover tools on the host OS or in other containers — that's DockMCP's job.
No sandboxing within the sandbox. Tools run with the same permissions as AI itself. SandboxMCP doesn't add an extra isolation layer for tool execution.

How It Fits Together

SandboxMCP completes the tooling stack of the AI Sandbox:

Component	Location	Purpose
AI Sandbox	Container	Secure environment where AI runs. Secrets hidden via volume mounts
SandboxMCP	Container (stdio)	Tool auto-discovery and execution inside the sandbox
DockMCP	Host OS (SSE)	Cross-container access — AI can check logs and run tests in other containers

SandboxMCP auto-registers on container startup. No manual setup required.

Try It

VS Code + DevContainer:

git clone https://github.com/YujiSuzuki/ai-sandbox-dkmcp.git
cd ai-sandbox-dkmcp
code .
# Cmd+Shift+P → "Dev Containers: Reopen in Container"

CLI (no VS Code needed):

git clone https://github.com/YujiSuzuki/ai-sandbox-dkmcp.git
cd ai-sandbox-dkmcp
./cli_sandbox/claude.sh

Once inside, try dropping your own tool in .sandbox/tools/ and asking AI:

"What tools are available?"
"What did we work on this week?"
"Show me token usage this month"

You don't have to tell AI which tool to use. It figures that out on its own.

What I Took Away

The binary mystery was a small thing. But it changed how I think about AI tooling.

I'm not claiming drop-in tools replace dedicated MCP servers — those are more capable and better integrated for specific use cases. But for the long tail of small, project-specific utilities that don't justify their own server, a plugin folder works remarkably well. The cost of an unused tool sitting in a directory is zero.

I built a search tool to find old conversations. AI used it to track down a mystery I didn't know I had. That's what happens when you stop installing tools for specific problems and start building a toolbox.

Appendix: The Actual Conversation

Everything above describes what happened. Here's how it actually looked — the unedited exchange between me and Claude Code that inspired this article.

This conversation was originally in Japanese. The following is a translated version.
Original: Zenn article (Japanese)

● ---
  Code Review Results

  Project: /workspace
  Mode: Git mode (staged changes)
  Review target: Staged changes (12 files, +1264 -46)
  Summary: Addition of usage-report.go, improvements to search-history.go
  (date filters, timezone support), toolparser separator support,
  documentation updates

  Issues Found

  Issue 1: Compiled binary is staged
  - File: .sandbox/sandbox-mcp/search-history
  - Line: N/A (binary, 3.5MB)
  - Basis: Best practice violation
  - Confidence: 85/100

  Binary files /dev/null and b/.sandbox/sandbox-mcp/search-history differ

  Go projects should not commit compiled binaries. It can be regenerated
  with make install, bloats the repository, and causes platform-dependent
  issues.

❯ new file:   .sandbox/sandbox-mcp/search-history
  This one?

● Yes, that's the one. .sandbox/sandbox-mcp/search-history is a compiled
  Go binary (3.5MB) included in staging.

  Since it can be regenerated with make install or go build, there's no
  need to commit it. To unstage:

  git reset HEAD .sandbox/sandbox-mcp/search-history

  You may also want to add it to .gitignore.

❯ When did I build this binary?

● Read 2 files (ctrl+o to expand)

● Bash(git log --all --diff-filter=A -- .sandbox/sandbox-mcp/search-history)
  ⎿  (No content)

● Found the cause in past conversations.

  In session 16f4a485-b7d (today, 18:53), the AI ran
  go build /workspace/.sandbox/tools/search-history.go to verify
  compilation — but without the -o flag, so the binary was written to
  the current directory (.sandbox/sandbox-mcp/).

  In another session (e33d09a7), it correctly used go build -o /dev/null,
  but session 16f4a485 forgot the -o flag, leaving the binary behind.

  It wasn't intentional — safe to unstage.

❯ Wait... you searched past conversation history? With search-history?

● Yes, exactly. Here's what I ran via SandboxMCP's run_tool:

  search-history.go -role tool -tool Bash -after 2026-02-09 "search-history" -context 100

  I filtered Bash tool executions containing "search-history" from today's
  sessions to pinpoint when and how go build was run.

  Review flagged the issue → investigation completed with its own tools.
  That's the beauty of .sandbox/tools/.

❯ That's incredible. Without the search, we'd never have known the cause, right?

● Exactly. Without search-history, "why is this binary here?" would have
  remained unanswered:

  - git log had nothing — the file was never committed
  - The file timestamp (18:53) tells you *when*, not *what happened*
  - The previous session's AI is gone

  The conversation history was the only record of "go build was run
  without -o", and search-history is what pulled that out.

  AI sessions are ephemeral. Without a way to search past sessions,
  questions like "who created this and when?" become unanswerable.
  It's unglamorous, but genuinely useful.

❯ This is amazing — can we write about this somehow?

That last question led to this article.

The part I find most interesting isn't that the AI solved the problem. It's that git log returned nothing, and instead of asking me for more context, it reached for a tool I'd forgotten was there — and used it in a way I hadn't anticipated when I wrote it.

This is Part 3 of the AI Sandbox series. Part 1: Your AI Assistant Can See Your Secrets — Here's How I Fixed It / Part 2: Official AI Sandboxes Arrived — Why I Published Mine Anyway

AI Sandbox + DockMCP is open source (MIT License). Feedback and contributions welcome.

Your AI Assistant Can See Your Secrets — Here's How I Fixed It

Yuji Suzuki — Tue, 03 Feb 2026 14:58:07 +0000

AI coding agents are incredible. They refactor code, write tests, debug across files. But there's a problem nobody talks about enough: they read everything in your project directory, including your .env files, API keys, and private certificates.

I found out the hard way.

The Incident

I was using Claude Code to investigate an issue that spanned both a server-side project and an iOS app. The server repo was my working directory, but the iOS source lived in a sibling directory. I asked Claude Code if it could see the iOS code too. It said yes — so I let it investigate.

What I didn't realize: the iOS project had its own .claude/settings.json with deny rules to protect API keys. But Claude Code only reads the settings from the directory it was launched in. The iOS project's deny rules were ignored. The AI read the API keys.

Fortunately, they were ad network keys — not catastrophic. But the experience stuck with me. I had configured the protection correctly, and it still didn't work because of a scoping limitation I didn't know about.

And the data backs this up. GitHub reported 39 million leaked secrets in repositories in 2024 alone. With 82% of developers now using AI tools, the attack surface is only growing.

The Problem Is Getting Worse, Not Better

2025 brought a wave of new attack vectors targeting AI coding tools specifically:

PromptPwnd — Attackers inject malicious instructions into PR descriptions and commit messages. When an AI agent processes these in CI/CD, it leaks secrets or modifies workflows. At least five Fortune 500 companies were affected.
IDEsaster — Prompt injection through legitimate IDE features. CVEs were issued for Cursor, Roo Code, JetBrains Junie, GitHub Copilot, and Claude Code.
Rules File Backdoor — Hidden Unicode characters in configuration files silently instruct AI to insert malicious code. Virtually invisible to developers during code review.

These aren't theoretical. They're happening now.

What Existing Solutions Do — and Don't Do

The industry is responding, and there are real options available now:

Claude Code Sandboxing uses OS-level primitives (Seatbelt on macOS, bubblewrap on Linux) to restrict filesystem writes and network access. You can also add Read deny rules in permissions to block AI from reading specific files. This is solid for preventing command execution attacks and prompt injection damage.

Docker AI Sandboxes run AI agents in isolated microVMs with their own Docker daemon. The agent can't touch your host system. Great for giving agents full autonomy without risking your machine.

Docker MCP Toolkit provides 200+ containerized MCP servers with built-in isolation and secret management.

These are good tools. But there are two gaps they don't fully address:

Gap 1: Filesystem-level secret hiding. Claude Code's deny rules are application-level — they depend on correct configuration and the AI tool respecting them. There are also scope limitations: deny rules don't traverse parent directories, so in a monorepo or multi-project workspace, settings in one project won't protect secrets in a sibling project. Docker AI Sandboxes sync your entire workspace directory into the microVM with no mechanism to exclude specific files. In both cases, a .env file sitting in your project directory is either visible or requires careful per-tool configuration to hide.

What if the secrets simply didn't exist in AI's filesystem? Not blocked by a rule, not filtered by a config — just not there.

Gap 2: Cross-container debugging. Docker AI Sandboxes are fully isolated — each sandbox can't communicate with others. Claude Code's sandbox restricts outbound access. But in a real microservice setup, AI needs to check API logs, run tests in other containers, and inspect services to be useful. How do you give it that access safely?

My Solution: AI Sandbox + DockMCP

The existing tools above are valuable — and you should use them. Claude Code's sandboxing reduces permission fatigue. Docker AI Sandboxes provide strong isolation for autonomous agents.

But I needed something that works at a different layer: making secrets physically absent from AI's filesystem, while still giving AI controlled access to other containers for debugging.

I built AI Sandbox — a Docker-based development environment that fills these two gaps:

Secret hiding: Specific files don't exist in AI's filesystem — not blocked, not filtered, just absent
Cross-container access: AI can check logs and run tests in other containers through a controlled gateway

It's complementary to existing tools. You can use Claude Code's sandbox inside the AI Sandbox for defense in depth.

How Secret Hiding Works

The trick is surprisingly simple: Docker volume mounts.

# docker-compose.yml
volumes:
  # AI sees an empty file instead of real .env
  - /dev/null:/workspace/my-app/.env:ro

tmpfs:
  # AI sees an empty directory instead of real secrets
  - /workspace/my-app/secrets:ro

When AI runs inside the container, it literally cannot see the real files. They don't exist in its filesystem. But other containers — the ones actually running your app — mount the real files normally.

AI Sandbox (where AI runs)
├── my-app/
│   ├── src/           ← AI can read and edit all code
│   ├── .env           ← Empty (mounted from /dev/null)
│   └── secrets/       ← Empty directory (tmpfs)

API Container (where your app runs)
├── my-app/
│   ├── src/           ← Same code
│   ├── .env           ← Real secrets
│   └── secrets/       ← Real private keys

No runtime agents scanning for secrets. No AI configuration that could be bypassed. The secrets simply don't exist in AI's world.

The risk with this approach is forgetting to hide a file. To catch that, the sandbox runs startup validation that automatically checks whether your AI tool's deny rules (e.g., .claude/settings.json) and your docker-compose.yml volume mounts are in sync. If a secret file is blocked in one but not the other, you get a warning on startup — before AI ever sees it.

How Cross-Container Access Works

Hiding secrets creates a new problem: AI can't access other containers for debugging. That's where DockMCP comes in.

DockMCP is an MCP (Model Context Protocol) server that runs on the host OS and acts as a controlled gateway between the AI sandbox and other Docker containers.

AI Sandbox  →  DockMCP (host)  →  API Container
  "show me       checks            returns last
   the logs"     security policy   100 log lines

AI can:

Read logs from any allowed container
Run whitelisted commands (like npm test)
Check resource usage (CPU, memory)
Inspect container configuration

AI cannot:

Start or stop containers
Access files outside allowed paths
Run arbitrary commands
Bypass the security policy

The security policy is defined in a simple YAML file:

security:
  mode: "moderate"
  allowed_containers:
    - "my-api-*"
    - "my-web-*"
  exec_whitelist:
    "my-api":
      - "npm test"
      - "npm run lint"
  blocked_paths:
    - "/etc/shadow"
    - "**/.env"

DockMCP also automatically masks sensitive data (passwords, API keys, tokens) in log output and command results, so even when AI reads logs from other containers, secrets don't leak through.

For the full configuration reference, see the DockMCP documentation.

Architecture Overview

┌─────────────────────────────────────────┐
│ Host OS                                 │
│                                         │
│  DockMCP Server (:8080)                 │
│    ├── Security policy enforcement      │
│    └── Container access gateway         │
│                                         │
│  Docker Engine                          │
│    ├── AI Sandbox                       │
│    │   ├── Claude Code / Gemini / etc.  │
│    │   └── secrets → hidden             │
│    │                                    │
│    ├── API Container                    │
│    │   └── secrets → real files         │
│    │                                    │
│    └── Web Container                    │
└─────────────────────────────────────────┘

What This Looks Like in Practice

Here's a real debugging session. I ask AI to help investigate a failing API endpoint:

Me: The /api/notes endpoint returns 500. Can you check the API logs?

AI uses DockMCP to fetch logs from the API container:

AI: I can see the error in the logs. There's a JWT verification failure at line 42 of auth.js. The token format changed after a recent update. Let me check the code...

AI reads the auth middleware code (visible in the sandbox), identifies the bug, and proposes a fix. It never sees the JWT secret key (hidden via volume mount), but it doesn't need to — it can see the code and the error logs.

Me: Looks good. Run the tests to make sure it passes.

AI runs npm test via DockMCP in the API container and confirms all tests pass.

The AI had everything it needed to debug and fix the issue, without ever accessing a single secret.

How to Try It

Minimal Setup (Sandbox Only)

If you just want secret hiding without cross-container access:

git clone https://github.com/YujiSuzuki/ai-sandbox-dkmcp.git
cd ai-sandbox-dkmcp
code .
# Cmd+Shift+P → "Dev Containers: Reopen in Container"

Edit docker-compose.yml to hide your secret files, and you're done.

Full Setup (Sandbox + DockMCP)

# 1. Clone and enter
git clone https://github.com/YujiSuzuki/ai-sandbox-dkmcp.git
cd ai-sandbox-dkmcp

# 2. Start DockMCP on host OS
cd dkmcp
make install
dkmcp serve --config configs/dkmcp.example.yaml

# 3. Open DevContainer in VS Code
code .
# Cmd+Shift+P → "Dev Containers: Reopen in Container"
# Or use the CLI sandbox (no VS Code needed):
# ./cli_sandbox/claude.sh or ./cli_sandbox/gemini.sh

# 4. Register DockMCP as an MCP server (inside the container)
claude mcp add --transport sse --scope user dkmcp http://host.docker.internal:8080/sse
# Or for Gemini CLI:
gemini mcp add --transport sse dkmcp http://host.docker.internal:8080/sse

The repo includes a demo application (SecureNote) so you can see the full flow in action. For detailed setup instructions, troubleshooting, and connection verification, see the README.

Honest Limitations

I want to be upfront about what this does and doesn't do:

Local development only. DockMCP has no authentication yet, so it's designed for local use only. I'd like to add authentication in the future, but no timeline has been set.
No network restriction by default. AI can still make outbound HTTP requests. You can add network restrictions using Anthropic's official firewall script or Docker network policies.
Docker required. The volume mount approach means you need a Docker-compatible runtime. No Docker, no secret hiding.
Only tested on macOS. It should work on Linux and Windows, but I haven't verified it.
Not a replacement for proper secrets management. This is a development-time protection layer. Use HashiCorp Vault, AWS Secrets Manager, etc. for production.
Complementary, not competing. This works alongside Claude Code's sandbox and Docker AI Sandboxes. Use them together for defense in depth.

Why This Matters

85% of developers now use AI coding tools (JetBrains, 2025). AI writes 29% of new code in the US. These tools aren't going away — they're becoming the default way we write software.

But the security model hasn't caught up. We give AI full read access to our projects and hope for the best. When something leaks, we rotate keys and move on.

We can do better. The approach doesn't have to be complicated:

Isolate AI in a container so secrets can be hidden at the filesystem level
Provide controlled access to other containers for debugging
Define explicit security policies for what AI can and cannot do

The AI Sandbox + DockMCP template is one implementation of this idea. Hit "Use this template" on GitHub to start your own.

The goal isn't to restrict AI — it's to let AI work freely in a space where secrets simply don't exist.

AI Sandbox + DockMCP is open source (MIT License). Contributions and feedback are welcome on GitHub.