Running NanoClaw in a Docker Shell Sandbox

Source: Docker Blog

Ever wanted to run a personal AI assistant that monitors your WhatsApp messages 24/7, but worried about giving it access to your entire system? Docker Sandboxes’ new shell sandbox type is the perfect solution. In this post, I’ll show you how to run NanoClaw, a lightweight Claude‑powered WhatsApp assistant, inside a secure, isolated Docker sandbox.

What is the Shell Sandbox?

Docker Sandboxes provides pre‑configured environments for running AI coding agents like Claude Code, Gemini CLI, and others. When you need to run a different agent or tool that isn’t built‑in, the shell sandbox drops you into an interactive Bash shell inside an isolated microVM. It offers a clean Ubuntu environment with Node.js, Python, Git, and common dev tools—no pre‑installed agent, no opinions. You install whatever you need.

Why Run NanoClaw in a Sandbox?

NanoClaw already runs its agents in containers, so it’s security‑conscious by design. Running the entire NanoClaw process inside a Docker sandbox adds another layer:

• Filesystem isolation – NanoClaw can only see the workspace directory you mount, not your home directory.
• Credential management – API keys are injected via Docker’s proxy, never stored inside the sandbox.
• Clean environment – No conflicts with your host’s Node.js version or global packages.
• Disposability – Nuke it and start fresh anytime with docker sandbox rm.

Prerequisites

• Docker Desktop installed and running.
• Docker Sandboxes CLI (docker sandbox command available) – v0.12.0 (nightly build as of Feb 13).
• An Anthropic API key available in an environment variable.

Setting It Up

Create the sandbox

mkdir -p ~/nanoclaw-workspace
docker sandbox create --name nanoclaw shell ~/nanoclaw-workspace

Connect to it

docker sandbox run nanoclaw

You’re now inside the sandbox—an Ubuntu shell running in an isolated VM. Everything from here on happens inside the sandbox.

Install Claude Code

The shell sandbox comes with Node.js 20 pre‑installed, so install Claude Code via npm:

npm install -g @anthropic-ai/claude-code

Configure the API key

The built‑in claude sandbox type configures the key automatically, but in a plain shell you must tell Claude Code to obtain its API key from Docker’s credential proxy:

mkdir -p ~/.claude && cat > ~/.claude/settings.json <<'EOF'
{
  "apiKeyHelper": "echo proxy-managed",
  "defaultMode": "bypassPermissions",
  "bypassPermissionsModeAccepted": true
}
EOF

apiKeyHelper makes Claude Code run echo proxy-managed to fetch the key. The sandbox’s network proxy intercepts outgoing API calls and swaps this sentinel value for your real Anthropic key, so the actual key never exists inside the sandbox.

Clone NanoClaw and install dependencies

cd ~/workspace
git clone https://github.com/shelajev/nanoclaw.git
cd nanoclaw
npm install

Run Claude and set up NanoClaw

NanoClaw uses Claude Code for its initial setup—configuring WhatsApp authentication, the database, and the container runtime:

claude

When Claude starts, run /setup and follow the prompts. Claude will guide you through scanning a WhatsApp QR code and configuring everything else.

Start NanoClaw

npm start

NanoClaw is now running and listening for WhatsApp messages inside the sandbox.

Managing the Sandbox

# List all sandboxes
docker sandbox ls

# Stop the sandbox (stops NanoClaw too)
docker sandbox stop nanoclaw

# Start it again
docker sandbox start nanoclaw

# Remove it entirely
docker sandbox rm nanoclaw

What Else Could You Run?

The shell sandbox isn’t specific to NanoClaw. Anything that runs on Linux and talks to AI APIs is a good fit:

• Custom agents built with the Claude Agent SDK or any other AI agent (Claude Code, Codex, GitHub Copilot, OpenCode, Kiro, etc.).
• AI‑powered bots and automation scripts.
• Experimental tools you don’t want running on your host.

The pattern is always the same: create a sandbox, install what you need, configure credentials via the proxy, and run it.

docker sandbox create --name my-shell shell ~/my-workspace
docker sandbox run my-shell