Security Sandboxing

Configure landlock, firejail, bubblewrap, or Docker sandboxing for tool execution isolation in NullClaw

NullClaw enforces security at every layer with multi-backend sandbox isolation for tool execution. Sandboxing restricts filesystem access, network access, and system resources.

Overview

NullClaw’s sandbox system:

Landlock

Native Linux kernel LSM (no dependencies)

Firejail

User-space sandboxing with profiles

Bubblewrap

Lightweight container runtime

Docker

Full container isolation

Quick Setup

Auto-Detection (Recommended)

config.json

{
  "security": {
    "sandbox": {
      "backend": "auto"
    }
  }
}

NullClaw automatically selects the best available backend:

Linux priority:

1. Landlock (native kernel, fastest)
2. Firejail (if installed)
3. Bubblewrap (if installed)
4. Docker (if daemon running)
5. None (application-layer only)

macOS priority:

1. Docker (if daemon running)
2. None (application-layer only)

Landlock requires Linux kernel 5.13+ and is the fastest option with zero external dependencies.

Sandbox Backends

Landlock (Native Linux)

Kernel-level access control (Linux 5.13+):

config.json

{
  "security": {
    "sandbox": {
      "backend": "landlock"
    }
  },
  "autonomy": {
    "workspace_only": true
  }
}

Features:

• Native kernel LSM (Linux Security Module)
• Zero external dependencies
• Fastest startup (<0.1ms overhead)
• Restricts filesystem access to workspace
• No network isolation (use with autonomy settings)

Availability:

# Check kernel version
uname -r  # Needs 5.13+

# NullClaw auto-detects support
nullclaw doctor

Restrictions:

• Read/write only within workspace directory
• No access to /etc, /home/*, system directories
• Symlink escape detection
• Null byte injection prevention

Firejail

User-space sandboxing with profiles:

config.json

{
  "security": {
    "sandbox": {
      "backend": "firejail"
    }
  }
}

Installation:

Ubuntu/Debian

sudo apt install firejail

Fedora

sudo dnf install firejail

Arch

sudo pacman -S firejail

Features:

• Filesystem isolation (--private, --whitelist)
• Network namespaces (--net=none)
• Process isolation (--seccomp)
• Profile-based configuration

Command wrapping:

# Without sandbox
sh -c "ls /tmp"

# With firejail
firejail --noprofile --private --whitelist=/workspace sh -c "ls /tmp"

Bubblewrap

Lightweight container runtime:

config.json

{
  "security": {
    "sandbox": {
      "backend": "bubblewrap"
    }
  }
}

Installation:

Ubuntu/Debian

sudo apt install bubblewrap

Fedora

sudo dnf install bubblewrap

Arch

sudo pacman -S bubblewrap

Features:

• Minimal container runtime
• Namespace isolation
• Bind mounts for workspace access
• No daemon required

Command wrapping:

# Without sandbox
sh -c "pwd"

# With bubblewrap
bw-wrap --ro-bind /usr /usr --bind /workspace /workspace sh -c "pwd"

Docker

Full container isolation:

config.json

{
  "security": {
    "sandbox": {
      "backend": "docker"
    }
  },
  "runtime": {
    "kind": "docker",
    "docker": {
      "image": "alpine:3.20",
      "network": "none",
      "memory_limit_mb": 512,
      "read_only_rootfs": true
    }
  }
}

Features:

• Complete process isolation
• Network isolation configurable
• Resource limits (CPU, memory, disk)
• Read-only root filesystem
• Custom base images

Prerequisites:

# Install Docker
curl -fsSL https://get.docker.com | sh

# Start daemon
sudo systemctl start docker

# Verify
docker --version

Command wrapping:

# Without sandbox
sh -c "whoami"

# With Docker
docker run --rm --network=none --read-only \
  -v /workspace:/workspace:rw alpine:3.20 sh -c "whoami"

None (Application-Layer Only)

Disable OS-level sandboxing:

config.json

{
  "security": {
    "sandbox": {
      "backend": "none"
    }
  }
}

Only use "backend": "none" for development or trusted environments. Rely on autonomy and workspace_only settings for safety.

Application-layer security still enforced:

• Workspace scoping (workspace_only: true)
• Command allowlists (allowed_commands)
• Path allowlists (allowed_paths)
• Risk assessment (block rm -rf /, dd, etc.)

Autonomy & Resource Limits

Workspace Scoping

config.json

{
  "autonomy": {
    "level": "supervised",
    "workspace_only": true,
    "max_actions_per_hour": 20
  }
}

Levels:

• supervised: Require approval for medium-risk actions
• full: Auto-approve low/medium-risk (still blocks high-risk)
• restricted: Approve even low-risk actions

workspace_only:

• true: Block access outside ~/.nullclaw/workspace/
• false: Allow access to allowed_paths

Command Allowlists

config.json

{
  "autonomy": {
    "allowed_commands": ["git", "npm", "python3"],
    "allowed_paths": ["/tmp", "~/projects"]
  }
}

Wildcard:

"allowed_commands": ["*"]

Allows all commands (use with workspace_only: true).

Blocked commands (always):

• rm -rf /
• dd if=/dev/zero
• :(){ :|:& };: (fork bomb)
• chmod -R 777 /
• Other destructive patterns

Resource Limits

config.json

{
  "security": {
    "resources": {
      "max_memory_mb": 512,
      "max_cpu_percent": 80,
      "max_disk_mb": 1024,
      "max_processes": 32,
      "max_open_files": 256
    }
  }
}

Enforced via:

• Docker: --memory, --cpus
• Firejail: --rlimit-* flags
• Bubblewrap: cgroup limits
• Landlock: Not enforced (use autonomy settings)

Audit Logging

Track all sandboxed operations:

config.json

{
  "security": {
    "audit": {
      "enabled": true,
      "retention_days": 90,
      "log_path": "~/.nullclaw/audit.log",
      "sign_events": true
    }
  }
}

Logged events:

• Tool executions
• Filesystem access
• Network requests
• Permission denials
• Security policy changes

Log format:

{
  "timestamp": "2026-03-01T12:34:56Z",
  "event": "tool_execute",
  "tool": "shell",
  "command": "ls /workspace",
  "sandbox": "landlock",
  "allowed": true,
  "signature": "ed25519:..."
}

Security Layers

NullClaw enforces defense-in-depth:

1. Gateway Pairing

   6-digit one-time code required for API access.

2. Channel Allowlists

   Empty allowlist denies all messages (explicit opt-in).

3. Workspace Scoping

   Filesystem access restricted to workspace directory.

4. Sandbox Isolation

   OS-level isolation via landlock/firejail/bubblewrap/docker.

5. Resource Limits

   CPU, memory, disk, process limits enforced.

6. Audit Trail

   Signed event log with configurable retention.

Configuration Profiles

Development (Relaxed)

config.json

{
  "security": {
    "sandbox": { "backend": "none" }
  },
  "autonomy": {
    "level": "full",
    "workspace_only": true,
    "allowed_commands": ["*"]
  }
}

Production (Strict)

config.json

{
  "security": {
    "sandbox": { "backend": "auto" },
    "resources": {
      "max_memory_mb": 256,
      "max_cpu_percent": 50
    },
    "audit": { "enabled": true }
  },
  "autonomy": {
    "level": "supervised",
    "workspace_only": true,
    "allowed_commands": ["git", "npm", "python3"],
    "max_actions_per_hour": 10
  },
  "gateway": {
    "require_pairing": true,
    "allow_public_bind": false
  }
}

Edge/Embedded (Minimal)

config.json

{
  "security": {
    "sandbox": { "backend": "landlock" }
  },
  "autonomy": {
    "level": "restricted",
    "workspace_only": true,
    "allowed_commands": [],
    "max_actions_per_hour": 5
  },
  "runtime": {
    "kind": "native"
  }
}

Troubleshooting

Sandbox Not Available

# Check detected backends
nullclaw doctor

# Check for landlock support
uname -r  # Need 5.13+

# Install firejail
sudo apt install firejail

# Install bubblewrap
sudo apt install bubblewrap

# Start Docker
sudo systemctl start docker

Permission Denied

# Check workspace directory exists
ls -la ~/.nullclaw/workspace/

# Check workspace_only setting
cat ~/.nullclaw/config.json | jq '.autonomy.workspace_only'

# Add path to allowlist
"allowed_paths": ["/your/custom/path"]

Command Blocked

Check allowlist:

"allowed_commands": ["*"]  // Allow all

Or add specific command:

"allowed_commands": ["git", "npm", "your-command"]

Docker Network Issues

Change network mode:

"runtime": {
  "docker": {
    "network": "bridge"  // From "none"
  }
}

Landlock Not Detected

Verify kernel support:

# Check kernel version
uname -r

# Must be 5.13 or higher
# Upgrade kernel if needed:
sudo apt update && sudo apt upgrade linux-generic

Advanced Configuration

Custom Docker Image

config.json

{
  "runtime": {
    "kind": "docker",
    "docker": {
      "image": "your-registry/custom-image:tag",
      "network": "custom-network",
      "memory_limit_mb": 1024,
      "cpu_shares": 512,
      "read_only_rootfs": true,
      "tmpfs": ["/tmp:rw,size=100m"]
    }
  }
}

Firejail Custom Profile

Create ~/.nullclaw/firejail.profile:

# Custom firejail profile
include /etc/firejail/default.profile

private
private-dev
private-tmp
whitelist ${HOME}/.nullclaw/workspace

net none
seccomp
caps.drop all
nonewprivs

Reference in config:

"security": {
  "sandbox": {
    "backend": "firejail",
    "firejail_profile": "~/.nullclaw/firejail.profile"
  }
}

Multi-Tier Sandboxing

Combine sandbox backends with tool-specific overrides:

config.json

{
  "security": {
    "sandbox": { "backend": "landlock" }
  },
  "tools": {
    "shell": {
      "sandbox_override": "docker"
    },
    "file_write": {
      "sandbox_override": "bubblewrap"
    }
  }
}

Benchmarks

Sandbox startup overhead (measured on Linux, 0.8 GHz edge core):

Backend	Overhead	Memory	Dependencies
None	0 ms	0 KB	None
Landlock	<0.1 ms	~8 KB	Kernel 5.13+
Bubblewrap	~5 ms	~2 MB	bwrap binary
Firejail	~15 ms	~5 MB	firejail binary
Docker	~200 ms	~50 MB	Docker daemon

Binary size impact:

• Landlock: +2 KB (compiled in)
• Others: No size impact (external binaries)

Next Steps

Hardware Integration

Connect Arduino, Raspberry Pi, STM32

AI Providers

Configure OpenAI, Anthropic, OpenRouter