⚠️ Important: NanoClaw does not publish an official Docker image. The application runs as a Node.js process on the host system, and uses Docker to spawn isolated containers for each agent session.
This page explains Docker’s role in NanoClaw’s architecture and provides guidance for Linux deployments.
NanoClaw uses Docker differently than typical containerized applications:
| Typical Docker Deployment | NanoClaw’s Docker Usage |
|---|---|
| App runs inside a container | App runs on host (Node.js process) |
| Single long-running container | Spawns short-lived containers per agent session |
| You pull a Docker image | You clone source and run locally |
| Container = application | Container = isolated agent sandbox |
Host System (Node.js + NanoClaw)
│
├── spawns ──→ [Docker Container: Agent Session 1]
├── spawns ──→ [Docker Container: Agent Session 2]
└── spawns ──→ [Docker Container: Agent Session 3]
Each agent session gets:
| Requirement | Details |
|---|---|
| Operating System | Linux (any distribution with Docker support) |
| Docker | Docker Engine 20+ with Docker Compose plugin |
| Node.js | Version 20 or higher |
| Git | For cloning the repository |
| Claude Code | Subscription or API access |
Debian/Ubuntu:
sudo apt update
sudo apt install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
RHEL/Fedora:
sudo dnf install -y docker docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
Arch Linux:
sudo pacman -S docker docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
Using NodeSource (Debian/Ubuntu):
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
Using Homebrew (macOS):
brew install node@20
git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw
claude
Then run /setup inside Claude Code. When prompted for container runtime, Docker will be used automatically on Linux.
NanoClaw’s architecture makes a traditional Docker image impractical:
If you need a containerized deployment for your specific use case, you can create a custom Dockerfile:
# ⚠️ UNOFFICIAL - For advanced users only
# This is NOT supported by the NanoClaw project
FROM node:20-alpine
# Install Docker CLI (for spawning agent containers)
RUN apk add --no-cache docker-cli git
# Docker socket mount required for spawning containers
# ⚠️ Security: Mounting docker.sock gives root-equivalent access
WORKDIR /app
RUN git clone https://github.com/qwibitai/nanoclaw.git .
RUN npm install
# Run as non-root user
RUN adduser -D nanoclaw
USER nanoclaw
CMD ["node", "src/index.ts"]
⚠️ Security Warning: Mounting docker.sock inside a container gives that container root-equivalent access to the host. Only use this approach if you fully understand the security implications.
For production deployments, use the source installation approach:
claude → /setup)This approach:
git pull| Platform | Container Runtime | Installation Method |
|---|---|---|
| macOS | Apple Container | Source clone + Claude Code |
| Linux | Docker | Source clone + Claude Code |
| Windows | WSL2 + Docker | Source clone + /setup-windows skill |
Any questions?
Feel free to contact us. Find all contact information on our contact page.