Security Sandboxing

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:

Landlock (native kernel, fastest)
Firejail (if installed)
Bubblewrap (if installed)
Docker (if daemon running)
None (application-layer only)

macOS priority:

Docker (if daemon running)
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
Fedora
Arch

sudo apt install firejail

sudo dnf install firejail

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
Fedora
Arch

sudo apt install bubblewrap

sudo dnf install bubblewrap

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:

Gateway Pairing

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

Channel Allowlists

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

Workspace Scoping

Filesystem access restricted to workspace directory.

Sandbox Isolation

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

Resource Limits

CPU, memory, disk, process limits enforced.

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

Get Started

Core Concepts

Configuration

Deployment

Guides

Documentation Index

​Overview

Landlock

Firejail

Bubblewrap

Docker

​Quick Setup

​Auto-Detection (Recommended)

​Sandbox Backends

​Landlock (Native Linux)

​Firejail

​Bubblewrap

​Docker

​None (Application-Layer Only)

​Autonomy & Resource Limits

​Workspace Scoping

​Command Allowlists

​Resource Limits

​Audit Logging

​Security Layers

​Configuration Profiles

​Development (Relaxed)

​Production (Strict)

​Edge/Embedded (Minimal)

​Troubleshooting

​Sandbox Not Available

​Permission Denied

​Command Blocked

​Docker Network Issues

​Landlock Not Detected

​Advanced Configuration

​Custom Docker Image

​Firejail Custom Profile

​Multi-Tier Sandboxing

​Benchmarks

​Next Steps

Hardware Integration

AI Providers

Overview

Quick Setup

Auto-Detection (Recommended)

Sandbox Backends

Landlock (Native Linux)

Firejail

Bubblewrap

Docker

None (Application-Layer Only)

Autonomy & Resource Limits

Workspace Scoping

Command Allowlists

Resource Limits

Audit Logging

Security Layers

Configuration Profiles

Development (Relaxed)

Production (Strict)

Edge/Embedded (Minimal)

Troubleshooting

Sandbox Not Available

Permission Denied

Command Blocked

Docker Network Issues

Landlock Not Detected

Advanced Configuration

Custom Docker Image

Firejail Custom Profile

Multi-Tier Sandboxing

Benchmarks

Next Steps