Container isolation

NanoClaw runs all agents inside containers (lightweight Linux VMs) to provide true OS-level isolation. This is the primary security boundary that makes Bash access and code execution safe.

Why containers?

Containers provide:

Process isolation - Agent processes can’t affect the host system
Filesystem isolation - Agents only see explicitly mounted directories
Resource limits - CPU/memory can be constrained (future)
Ephemeral execution - Fresh environment per invocation, no persistence
Non-root execution - Agents run as unprivileged user

NanoClaw uses Docker by default for cross-platform compatibility. On macOS, you can use Apple Container instead (via /convert-to-apple-container skill).

Container architecture

Base image

The container is built from container/Dockerfile:

FROM node:22-slim

# System dependencies for Chromium
RUN apt-get update && apt-get install -y \
    chromium \
    fonts-liberation \
    fonts-noto-color-emoji \
    # ... other dependencies
    && rm -rf /var/lib/apt/lists/*

# Browser executable paths
ENV AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
ENV PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium

# Install global tools
RUN npm install -g agent-browser @anthropic-ai/claude-code

# Copy and build agent-runner
WORKDIR /app
COPY agent-runner/package*.json ./
RUN npm install
COPY agent-runner/ ./
RUN npm run build

# Create workspace directories
RUN mkdir -p /workspace/group /workspace/global /workspace/extra /workspace/ipc/messages /workspace/ipc/tasks /workspace/ipc/input

# Entrypoint script
RUN printf '#!/bin/bash\nset -e\ncd /app && npx tsc --outDir /tmp/dist 2>&1 >&2\nln -s /app/node_modules /tmp/dist/node_modules\nchmod -R a-w /tmp/dist\ncat > /tmp/input.json\nnode /tmp/dist/index.js < /tmp/input.json\n' > /app/entrypoint.sh && chmod +x /app/entrypoint.sh

# Set ownership for writable directories
RUN chown -R node:node /workspace && chmod 777 /home/node

# Switch to non-root user
USER node

WORKDIR /workspace/group
ENTRYPOINT ["/app/entrypoint.sh"]

Key components:

Base: node:22-slim (Debian-based, minimal)
Browser: Chromium with all dependencies
Tools: agent-browser for browser automation
Runtime: @anthropic-ai/claude-code (Claude Agent SDK)
User: node (uid 1000, non-root)
Working directory: /workspace/group

Entrypoint flow

The entrypoint script (/app/entrypoint.sh):

Recompile agent-runner: npx tsc --outDir /tmp/dist
- Allows per-group customization of agent runner code
- Compiled output is read-only to prevent runtime tampering
Read input from stdin: cat > /tmp/input.json
- Secrets passed via stdin (never written to disk)
- Input file deleted immediately after read
Execute agent: node /tmp/dist/index.js < /tmp/input.json
- Runs agent-runner with input
- Outputs JSON results to stdout
Container exits: Cleaned up automatically via --rm flag

The agent-runner is recompiled on every container start. This allows agents to modify their own tools and behavior by editing files in /workspace/group/ or their agent-runner source.

Volume mounts

Containers only see what’s explicitly mounted:

Main group mounts

mounts = [
  {
    hostPath: '/path/to/nanoclaw',
    containerPath: '/workspace/project',
    readonly: true
  },
  {
    hostPath: '/path/to/nanoclaw/groups/main',
    containerPath: '/workspace/group',
    readonly: false
  },
  {
    hostPath: '/path/to/nanoclaw/data/sessions/main/.claude',
    containerPath: '/home/node/.claude',
    readonly: false
  },
  {
    hostPath: '/path/to/nanoclaw/data/ipc/main',
    containerPath: '/workspace/ipc',
    readonly: false
  },
  {
    hostPath: '/path/to/nanoclaw/data/sessions/main/agent-runner-src',
    containerPath: '/app/src',
    readonly: false
  }
]

Non-main group mounts

mounts = [
  {
    hostPath: '/path/to/nanoclaw/groups/{group-folder}',
    containerPath: '/workspace/group',
    readonly: false
  },
  {
    hostPath: '/path/to/nanoclaw/groups/global',
    containerPath: '/workspace/global',
    readonly: true
  },
  {
    hostPath: '/path/to/nanoclaw/data/sessions/{group-folder}/.claude',
    containerPath: '/home/node/.claude',
    readonly: false
  },
  {
    hostPath: '/path/to/nanoclaw/data/ipc/{group-folder}',
    containerPath: '/workspace/ipc',
    readonly: false
  },
  {
    hostPath: '/path/to/nanoclaw/data/sessions/{group-folder}/agent-runner-src',
    containerPath: '/app/src',
    readonly: false
  }
]

Notice that non-main groups do NOT have /workspace/project mounted. They cannot access the NanoClaw source code or other groups’ folders.

Mount security

All mounts are validated against the allowlist at ~/.config/nanoclaw/mount-allowlist.json:

{
  "/Users/you/projects/website": {
    "reason": "Website deployment tasks",
    "addedBy": "main",
    "addedAt": "2026-02-28T10:30:00Z",
    "nonMainReadOnly": true
  }
}

Validation steps:

Resolve symlinks to real path
Check against blocked patterns (.ssh, .env, etc.)
Verify path is in allowlist (for additional mounts)
Enforce nonMainReadOnly for non-main groups
Reject container paths with .. or absolute paths

Container lifecycle

Spawn

const container = spawn('docker', [
  'run',
  '-i',                    // Interactive (stdin)
  '--rm',                  // Remove on exit
  '--name', containerName, // Unique name
  '-e', `TZ=${TIMEZONE}`,  // Pass timezone
  '--user', `${uid}:${gid}`, // Run as host user (if not root/1000)
  '-v', 'host:container',  // Volume mounts
  // ... more mounts
  'nanoclaw-agent:latest'  // Image name
]);

User mapping:

If host uid is 0 (root): Run as container’s node user (uid 1000)
If host uid is 1000: Run as node user (no mapping needed)
Otherwise: Run as host uid (via --user flag)

This ensures bind-mounted files are accessible (same uid on both sides).

Execute

Secrets passed: Via stdin JSON, never written to disk
Stdout streaming: Parsed for output markers in real-time
Stderr logging: Logged at debug level (SDK writes lots of debug info)
Timeout tracking: Hard timeout with activity-based reset
Graceful shutdown: docker stop (SIGTERM) before SIGKILL

Cleanup

Containers are ephemeral:

--rm flag: Docker removes container on exit
Logs persisted: Written to groups/{folder}/logs/ before removal
Sessions persisted: .claude/ mounted, survives container death
Group files persisted: /workspace/group mounted, survives restart

Even if the container crashes, all data in mounted directories persists. Only the container itself is ephemeral.

Output streaming

The container uses sentinel markers for robust output parsing:

const OUTPUT_START_MARKER = '---NANOCLAW_OUTPUT_START---';
const OUTPUT_END_MARKER = '---NANOCLAW_OUTPUT_END---';

// Container writes:
console.log(OUTPUT_START_MARKER);
console.log(JSON.stringify({ status: 'success', result: 'Hello!' }));
console.log(OUTPUT_END_MARKER);

// Host parses:
const output = extractBetweenMarkers(stdout, OUTPUT_START_MARKER, OUTPUT_END_MARKER);
const parsed = JSON.parse(output);

Why markers?

SDK writes debug logs to stdout
Markers ensure JSON isn’t corrupted by debug output
Supports multiple outputs per container (streaming)
Robust against stderr bleeding into stdout

Streaming mode: When onOutput callback is provided:

Parse buffer accumulates stdout chunks
Each complete marker pair triggers onOutput(parsed)
Session ID tracked across multiple outputs
Container stays alive between outputs (idle timeout)
_close sentinel in IPC signals graceful shutdown

Timeouts

Two timeout mechanisms:

Hard timeout (container timeout)

Default: 30 minutes (CONTAINER_TIMEOUT)
Configurable: Per-group via containerConfig.timeout
Grace period: At least IDLE_TIMEOUT + 30s
Reset on activity: Resets whenever output markers are parsed
Enforcement: docker stop (SIGTERM), then SIGKILL after 15s

Timeout after output: If a container times out after producing output, it’s considered idle cleanup (not an error):

if (timedOut && hadStreamingOutput) {
  // Idle cleanup, not failure
  return { status: 'success', result: null };
}

Idle timeout (stdin close)

Default: 30 minutes (IDLE_TIMEOUT)
Purpose: Close container when no follow-up messages arrive
Mechanism: Write _close sentinel to IPC input directory
Agent behavior: Exit gracefully when _close detected
Reset on: New messages piped to container

For tasks:

Tasks use shorter close delay: 10 seconds
Tasks are single-turn (no follow-ups expected)
Closes automatically after producing result

Idle timeout is agent-cooperative (relies on agent checking IPC). Hard timeout is enforced by the container runtime (kills process if exceeded).

Resource limits

Currently no CPU/memory limits enforced. Future enhancement:

args.push('--memory', '2g');      // 2GB RAM limit
args.push('--cpus', '2');         // 2 CPU cores
args.push('--pids-limit', '100'); // Max 100 processes

Logging

All container runs are logged: Log location: groups/{folder}/logs/container-{timestamp}.log Log contents (verbose mode or errors):

=== Container Run Log ===
Timestamp: 2026-02-28T10:30:45.123Z
Group: Family Chat
IsMain: false
Duration: 12345ms
Exit Code: 0
Stdout Truncated: false
Stderr Truncated: false

=== Input ===
{ prompt: "...", sessionId: "...", ... }

=== Container Args ===
docker run -i --rm --name nanoclaw-family-chat-1234567890 ...

=== Mounts ===
/path/to/groups/family-chat -> /workspace/group
/path/to/sessions/family-chat/.claude -> /home/node/.claude (ro)
...

=== Stderr ===
[SDK debug logs]

=== Stdout ===
---NANOCLAW_OUTPUT_START---
{"status":"success","result":"Hello!"}
---NANOCLAW_OUTPUT_END---

Log verbosity:

Success + non-verbose: Summary only (input length, mount count)
Success + verbose (LOG_LEVEL=debug): Full input/output
Error: Always full input/output/stderr

Set LOG_LEVEL=debug in .env to enable verbose logging for all container runs.

Container runtime

NanoClaw detects and uses the available container runtime:

// src/container-runtime.ts
export const CONTAINER_RUNTIME_BIN = 
  fs.existsSync('/usr/local/bin/orb') ? 'orb' :  // Apple Container
  fs.existsSync('/usr/local/bin/docker') ? 'docker' :  // Docker (macOS)
  'docker';  // Default (Linux, Windows)

Supported runtimes:

Docker (default): Cross-platform, well-tested
Apple Container (macOS): Lightweight, native virtualization

Runtime-specific commands:

// Read-only mount args
if (runtime === 'orb') {
  return ['-v', `${hostPath}:${containerPath}:ro`];
} else {
  return ['-v', `${hostPath}:${containerPath}:ro`];
}

Skills and MCP servers

Skills synced to each container:

Copy from shared: container/skills/{skill-name}/ → data/sessions/{group}/.claude/skills/{skill-name}/
Available to agent: Claude Agent SDK loads from .claude/skills/
Per-group customization: Each group gets a copy, can modify independently

MCP servers:

Configured in agent-runner source (container/agent-runner/src/index.ts)
Built-in: nanoclaw MCP server (task scheduling, message sending)
Custom: Add by modifying agent-runner code

Adding a custom MCP server

Edit data/sessions/{group}/agent-runner-src/index.ts

Import and register MCP server:

import { CustomMcpServer } from 'custom-mcp-server';
const mcpServers = [
  new NanoClawMcpServer(),
  new CustomMcpServer()
];

Next container spawn will recompile with new server
Tools available to agent immediately

Browser automation

Chromium runs inside the container:

Executable: /usr/bin/chromium
CLI: agent-browser (installed globally)
Headless: Always (no display in container)
User data: Stored in group folder (persists across runs)
Network: Full access (same as host, no restrictions)

Example usage:

agent-browser snapshot https://example.com
agent-browser click @e1  # Click element 1
agent-browser pdf https://example.com output.pdf

Security implications

What containers protect against

Filesystem access: Agents can’t read ~/.ssh or other sensitive paths
Process interference: Agents can’t kill host processes or inject code
Persistence: Containers are ephemeral, no state survives unless mounted
Privilege escalation: Non-root execution limits kernel attack surface

What containers DON’T protect against

Network access: Agents have full network access (can exfiltrate data)
Mounted directory tampering: Agents can modify anything in mounted directories
Credential exposure: Mounted credentials (Claude tokens) are readable
Resource exhaustion: No CPU/memory limits (can DoS host)

Containers provide filesystem isolation, not network isolation. Agents can make arbitrary HTTP requests and exfiltrate data over the network.

Troubleshooting

Container won’t start

Check Docker is running: docker ps
Check image exists: docker images | grep nanoclaw-agent
Rebuild image: ./container/build.sh
Check logs: groups/{folder}/logs/

Container timeout

Check timeout setting: CONTAINER_TIMEOUT in .env
Check if task is legitimately slow (increase timeout)
Check idle timeout: IDLE_TIMEOUT (controls stdin close)
Review logs for last activity timestamp

Permission errors

Check mount paths are readable by host user
Check uid/gid mapping (logged in verbose mode)
Verify allowlist includes path (for additional mounts)
Check symlink resolution didn’t change path

Output not parsed

Check for output markers in logs
Verify agent-runner is writing markers correctly
Check stdout isn’t truncated (CONTAINER_MAX_OUTPUT_SIZE)
Review stderr for SDK errors

Get Started

Core Concepts

Features

Integrations

Advanced

Container isolation

Why containers?

Container architecture

Base image

Entrypoint flow

Volume mounts

Main group mounts

Non-main group mounts

Mount security

Container lifecycle

Spawn

Execute

Cleanup

Output streaming

Timeouts

Hard timeout (container timeout)

Idle timeout (stdin close)

Resource limits

Logging

Container runtime

Skills and MCP servers

Browser automation

Security implications

What containers protect against

What containers DON’T protect against

Troubleshooting

Container won’t start

Container timeout

Permission errors

Output not parsed

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Integrations

Advanced

​Why containers?

​Container architecture

​Base image

​Entrypoint flow

​Volume mounts

​Main group mounts

​Non-main group mounts

​Mount security

​Container lifecycle

​Spawn

​Execute

​Cleanup

​Output streaming

​Timeouts

​Hard timeout (container timeout)

​Idle timeout (stdin close)

​Resource limits

​Logging

​Container runtime

​Skills and MCP servers

​Browser automation

​Security implications

​What containers protect against

​What containers DON’T protect against

​Troubleshooting

​Container won’t start

​Container timeout

​Permission errors

​Output not parsed

​Related topics

Build docs developers (and LLMs) love

Why containers?

Container architecture

Base image

Entrypoint flow

Volume mounts

Main group mounts

Non-main group mounts

Mount security

Container lifecycle

Spawn

Execute

Cleanup

Output streaming

Timeouts

Hard timeout (container timeout)

Idle timeout (stdin close)

Resource limits

Logging

Container runtime

Skills and MCP servers

Browser automation

Security implications

What containers protect against

What containers DON’T protect against

Troubleshooting

Container won’t start

Container timeout

Permission errors

Output not parsed

Related topics