It's fast. It's capable. It can read files, modify code, run commands, and generally behave like a very efficient developer sitting at your keyboard.

And that's exactly why I decided to put it in a sandbox.

Not because I distrust Claude.

Not because I expect malicious behavior.

But because I believe in the principle of least privilege.

If a tool only needs access to one folder, why give it access to my entire machine?

So I built a Docker-based sandbox that isolates Claude Code to a single directory on my system. Then I documented the entire process. Then I stress-tested that documentation. Then I invited another AI to critique it. Then I revised it again. Now granted there is plenty of documentation out there to guide you through this setup (most notable is Anthorpic's own documentation you can read here…), but I found most of them lacking the hand-holding I felt I needed to comprehend the context and the rationale behind it all. If this helps just one other person out there, it was worth the effort to document!

This article isn't just about Docker.

It's about boundaries, verification, and the importance of writing documentation that survives contact with reality.

Native Mode vs. Sandbox Mode

By default, Claude Code runs natively.

That means:

  • It has access to every file your user account can access.
  • Your Desktop, Documents, Downloads, SSH keys — all visible.
  • It runs as you.

That might be fine. But it's broad.

In sandbox mode, Claude runs inside a Docker container.

Only one folder on my machine is mounted into that container. Everything else is invisible — not blocked, not restricted — just nonexistent from the container's perspective.

Conceptually, it looks like this:

Host Machine ├── ~/Desktop (not mounted) ├── ~/Documents (not mounted) ├── ~/Photos (not mounted) └── ~/claude_sandbox ← only this is visible

Docker Container └── /workspace → mapped to ~/claude_sandbox

If the container can't see a path, it can't access it. That's stronger than "please don't."

Why I Documented Everything

I didn't just want a working setup.

I wanted something:

  • Reproducible
  • Auditable
  • Verifiable
  • Understandable by someone else

Because powerful AI tools deserve thoughtful boundaries — and good boundaries deserve good documentation.

I wrote a full step-by-step guide explaining:

  • The Dockerfile
  • The compose configuration
  • The permission model
  • The SSH handling
  • The verification process
  • The difference between ephemeral and persistent containers
  • The common mistakes I personally made

And here's the important part:

The documentation changed as I used it.

Where Things Broke (And Why That Was Valuable)

At first, I used:

docker compose run — rm claude-sandbox

It worked.

But then things got confusing:

  • Container names weren't stable.
  • docker inspect didn't behave how I expected.
  • Writable-layer state disappeared between sessions.
  • My verification workflow became unreliable.

Named volumes persisted authentication tokens — which is good — but container-level configuration did not persist between runs.

That forced me to rethink the architecture.

I moved to a persistent container model:

docker compose up -d docker compose exec claude-sandbox claude

That one change simplified everything:

  • Stable container identity
  • Reliable inspection
  • Persistent writable-layer state
  • Faster session startup
  • Cleaner mental model

The documentation improved because reality pushed back.

And that's exactly what good documentation is supposed to survive.

Verification: Don't Let One AI Grade Its Own Homework

Claude helped me design the sandbox.

But asking Claude to verify its own architecture didn't feel right.

So I used a second LLM as an independent reviewer.

I created a canary file outside the sandbox and attempted to access it from inside the container.

I inspected mount points.

I verified the container was not running in privileged mode.

I confirmed the Docker socket wasn't mounted.

I inspected HostConfig.Binds.

I forced observable proof instead of trusting a narrative.

That process changed how I think about AI-assisted engineering.

It's not about trust.

It's about verification.

The Real Lesson: Documentation Is a Security Boundary

The biggest insight wasn't technical.

It was this:

If your documentation doesn't anticipate mistakes, someone will make them.

In my case, I:

  • Accidentally shadowed the native claude command with a shell function.
  • Confused ephemeral containers with persistent state.
  • Under-explained the difference between named volumes and writable layers.
  • Initially overstated one of my own technical claims.

Every time something was unclear, the documentation improved.

That's how it should work.

Documentation isn't just instructions.

It's the interface between intention and behavior.

Why This Matters

AI coding tools are powerful.

And power without boundaries isn't innovation — it's entropy.

Docker isn't magic.

LLMs aren't magic.

Security isn't magic.

But layered boundaries, verified assumptions, and careful documentation?

That's engineering.

An Invitation to the Claude Code Community

This setup works for me.

But I don't assume it's perfect.

If you try this process and:

  • Run into confusing steps
  • Discover edge cases
  • See architectural improvements
  • Spot blind spots in my reasoning
  • Identify better verification strategies

I want to hear about it.

The goal isn't to defend the design.

The goal is to improve it.

If we're going to build with AI tools that can read and modify our systems, we should hold ourselves to a higher standard of operational clarity.

If you're using Claude Code — or any AI coding assistant — and thinking about isolation, reproducibility, or documentation quality, let's compare notes.

Good systems thinking improves through feedback.

Final Thought

I didn't sandbox Claude Code because I was afraid of it.

I sandboxed it because I respect it.

And powerful tools deserve thoughtful boundaries.

If you're interested in the full technical guide, verification prompts, and setup templates, I've published the complete documentation in my repository.

Try it.

Break it.

Improve it.

Then tell me what you learned.

The source files:

🧠 + 🤖 This article was produced in partnership with AI tools. They helped me think faster. They did not think for me. Every conclusion, correction, and claim here is ultimately mine — and so is the responsibility.