Technical Document: NanoClaw Containerized AI Agent Framework Evaluation
Document Version: 1.0 | Evaluation Date: 2026-04-05 | Classification: UNCONTROLLED TECHNICAL DATA
Abstract
This document details a comprehensive evaluation of NanoClaw, a containerized AI agent framework, for deployment in a production server environment. The evaluation tested build processes, runtime behavior, security isolation, and integration with existing decentralized AI infrastructure. Multiple critical failures were identified that prevent safe production deployment.
1. Introduction
1.1 Purpose
Evaluate NanoClaw's suitability for:
- Autonomous AI security research and exploit testing
- Integration with existing local AI infrastructure (local models, vector databases, workflow automation)
- Safe deployment in production environments with client-facing services
- Alignment with decentralization and privacy-focused architecture
1.2 Environment Overview
Offline
Security Requirement
Security Requirements: No cloud dependencies, offline-first operation, client service protection mandatory
2. Architecture Assessment
2.1 NanoClaw Design Intent
NanoClaw is designed as a host-level container orchestrator that:
- Spawns and manages agent containers dynamically
- Requires Docker CLI access to control container lifecycle
- Uses IPC-based communication between orchestrator and agents
- Supports browser automation and tool execution
2.2 Environmental Mismatch
| Requirement |
NanoClaw Architecture |
Production Environment |
| Deployment Model |
Host-level orchestrator |
Containerized services |
| Docker Access |
Full daemon control required |
Socket exposure = security risk |
| Cloud Dependency |
Originally Claude API (modified to local) |
Offline-first mandatory |
| Isolation |
Container-per-agent |
Production services share host network |
| Client Safety |
Orchestrator has full Docker control |
Client services must be protected |
3. Build Process Failures
Failure Point 1: Missing Expected Directory Structure
Expected: agent-runner/ directory
Actual: src/ directory
Impact: Build failures requiring Dockerfile modification
COPY agent-runner/package*.json ./
# ERROR: failed to calculate checksum: "/agent-runner": not found
Resolution Attempt: Modified Dockerfile to copy from src/ instead of agent-runner/
Failure Point 2: TypeScript Compilation Failures
Error: tsc showing help output instead of compiling
Root Cause: tsconfig.json not copied to build directory
tsc: The TypeScript Compiler - Version 5.9.3
COMMON COMMANDS
tsc - Compiles the current project (tsconfig.json in the working directory.)
Resolution Attempt: Added tsconfig.json to COPY instruction in Dockerfile
Failure Point 3: Missing npm Dependencies
Error: Cannot find package '@onecli-sh/sdk'
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@onecli-sh/sdk'
imported from /tmp/dist/index.js
Impact: Runtime failures even after successful build
Resolution Attempt: Added explicit npm install for missing packages
Failure Point 4: Permission Errors
Error: EACCES: permission denied during TypeScript compilation
error TS5033: Could not write file '/tmp/dist/channels/index.d.ts':
EACCES: permission denied, open '/tmp/dist/channels/index.d.ts'
Root Cause: /tmp/dist owned by root, container runs as non-root node user
Impact: Container crash loops, service unavailable
4. Runtime Failures
Critical Failure Point 5: Docker Daemon Access
ERROR: Failed to reach container runtime
/bin/sh: 1: docker: not found
╔════════════════════════════════════════════════════════════════╗
║ FATAL: Container runtime failed to start ║
║ ║
║ Agents cannot run without a container runtime. To fix: ║
║ 1. Ensure Docker is installed and running ║
║ 2. Run: docker info ║
║ 3. Restart NanoClaw ║
╚════════════════════════════════════════════════════════════════╝
Root Cause: NanoClaw orchestrator requires Docker socket access to spawn agent containers. Even with Docker CLI installed in the image, the orchestrator cannot communicate with the host Docker daemon without socket mounting.
Security Implication: Mounting /var/run/docker.sock inside a container grants full control over the host Docker daemon, which equals root access to the host system. This is unacceptable for production environments with client-facing services.
Failure Point 6: Container Orchestration Conflicts
Status: All NanoClaw containers entered restart loops
Status: Restarting (1) - containers continuously crashing
Root Cause: Orchestrator failure prevents agent initialization
Impact: Complete service unavailability despite successful image build
Success Point: gVisor Isolation Configuration
Status: gVisor runtime configuration worked correctly
Research Agent Runtime: runsc (gVisor) ✓
Content Agent Runtime: runc (standard) ✓
Orchestrator Runtime: runc (standard) ✓
Note: Only the research agent required gVisor isolation (for exploit testing). Content generation and orchestration services used standard Docker runtime appropriately.
Limitation: gVisor configuration success did not resolve fundamental architecture mismatches.
5. Security Analysis
5.1 Docker Socket Exposure Risk
| Risk Level |
Access Type |
Impact |
| CRITICAL |
/var/run/docker.sock mounted |
Full host compromise possible |
| HIGH |
Container escape via Docker API |
Production services at risk |
| MEDIUM |
Privilege escalation |
Non-root container gains root |
Conclusion: NanoClaw's requirement for Docker socket access is fundamentally incompatible with production environments where client services must be protected.
5.2 Network Architecture Conflicts
Issue: NanoClaw orchestrator and agents require host network access to:
- Reach target systems for security testing
- Communicate with local AI models
- Access existing infrastructure services
Conflict: Host network mode reduces isolation boundaries between NanoClaw services and production services.
5.3 Cloud Dependency (Original Design)
Original Issue: NanoClaw designed for Anthropic Claude API
Original Dockerfile: npm install -g @anthropic-ai/claude-code
Modification Required: Replaced with local Ollama integration
Modified: npm install ollama axios node-fetch --save
Status: Successfully modified for offline-first operation, but this was one of few successful modifications.
6. Alternative Approaches Tested
6.1 Open-Terminal Integration
Tested: Existing open-terminal service for command execution
Result: Network access confirmed (ping, curl successful) ✓
Limitation: Manual execution only, no AI autonomy
Viability: Suitable for manual research workflows, does not provide autonomous AI testing capabilities.
6.2 n8n Workflow Automation
Tested: Existing workflow automation service
Result: Can trigger open-terminal via webhooks ✓
Limitation: Semi-autonomous only, requires workflow configuration
Viability: Viable alternative for semi-autonomous testing without NanoClaw's security risks.
6.3 Custom Research Container
Proposed: Purpose-built container with research tools
- Base: Kali Linux or similar
- Isolation: gVisor (runsc runtime)
- Tools: nmap, metasploit, burpsuite (explicit allowlist)
Status: Not fully implemented, but represents safer alternative architecture.
7. Recommendations
7.1 For Production Deployments
DO NOT DEPLOY NanoClaw in production environments where:
- Client-facing services share the same host
- Docker socket exposure creates unacceptable risk
- Production service availability is critical
- Regulatory or compliance requirements mandate strict isolation
7.2 For Research/Lab Environments
NanoClaw may be suitable for:
- Dedicated research hardware (no production services)
- Isolated lab networks (no client access)
- Testing and evaluation purposes only
- Environments where Docker socket exposure is acceptable
7.3 Recommended Alternative Architecture
┌─────────────────────────────────────────────────────────────┐
│ PRODUCTION STACK (Existing) │
├─────────────────────────────────────────────────────────────┤
│ Open WebUI ←→ Qdrant ←→ Ollama ←→ n8n ←→ Grafana │
│ (Client-facing, unchanged, NO gVisor) │
└─────────────────────────────────────────────────────────────┘
↑
│ API integration (webhooks)
│
┌─────────────────────────────────────────────────────────────┐
│ RESEARCH LAYER │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ open-terminal │ │ Custom Research│ │
│ │ (Manual) │ │ Container │ │
│ │ network: host │ │ (gVisor) │ │
│ │ Standard Docker│ │ runsc runtime │ │
│ └─────────────────┘ └─────────────────┘ │
│ ↑ ↑ │
│ Researcher manually Isolated exploit │
│ executes commands testing only │
└─────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ REPORTING PIPELINE │
│ Results → Open WebUI KB/Messaging → Website Publication │
│ Results → Static files (nginx folder) │
│ Results → Grafana dashboards │
└─────────────────────────────────────────────────────────────┘
8. Conclusion
After comprehensive evaluation, NanoClaw is not recommended for production deployment in environments with client-facing services. The fundamental architecture requires Docker socket access, creating unacceptable security risks.
Critical Issues
- Docker socket requirement = host compromise risk
- Host-level orchestrator design conflicts with containerized production
- Multiple build failures requiring extensive modification
- Runtime failures preventing service availability
Viable Alternatives
- Existing open-terminal + n8n workflow (semi-autonomous)
- Custom research containers with gVisor isolation
- Manual testing with documented workflows
- QEMU/KVM VMs for high-risk exploit testing
Evaluation Status: Complete | Recommendation: Do Not Deploy | Alternative: Use Existing Stack