> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nullclaw/nullclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CardGroup cols={4}>
  <Card title="Landlock" icon="lock">
    Native Linux kernel LSM (no dependencies)
  </Card>

  <Card title="Firejail" icon="fire">
    User-space sandboxing with profiles
  </Card>

  <Card title="Bubblewrap" icon="box">
    Lightweight container runtime
  </Card>

  <Card title="Docker" icon="docker">
    Full container isolation
  </Card>
</CardGroup>

## Quick Setup

### Auto-Detection (Recommended)

```json config.json theme={null}
{
  "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)

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

## Sandbox Backends

### Landlock (Native Linux)

Kernel-level access control (Linux 5.13+):

```json config.json theme={null}
{
  "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:**

```bash theme={null}
# 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:

```json config.json theme={null}
{
  "security": {
    "sandbox": {
      "backend": "firejail"
    }
  }
}
```

**Installation:**

<Tabs>
  <Tab title="Ubuntu/Debian">
    ```bash theme={null}
    sudo apt install firejail
    ```
  </Tab>

  <Tab title="Fedora">
    ```bash theme={null}
    sudo dnf install firejail
    ```
  </Tab>

  <Tab title="Arch">
    ```bash theme={null}
    sudo pacman -S firejail
    ```
  </Tab>
</Tabs>

**Features:**

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

**Command wrapping:**

```bash theme={null}
# Without sandbox
sh -c "ls /tmp"

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

### Bubblewrap

Lightweight container runtime:

```json config.json theme={null}
{
  "security": {
    "sandbox": {
      "backend": "bubblewrap"
    }
  }
}
```

**Installation:**

<Tabs>
  <Tab title="Ubuntu/Debian">
    ```bash theme={null}
    sudo apt install bubblewrap
    ```
  </Tab>

  <Tab title="Fedora">
    ```bash theme={null}
    sudo dnf install bubblewrap
    ```
  </Tab>

  <Tab title="Arch">
    ```bash theme={null}
    sudo pacman -S bubblewrap
    ```
  </Tab>
</Tabs>

**Features:**

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

**Command wrapping:**

```bash theme={null}
# Without sandbox
sh -c "pwd"

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

### Docker

Full container isolation:

```json config.json theme={null}
{
  "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:**

```bash theme={null}
# Install Docker
curl -fsSL https://get.docker.com | sh

# Start daemon
sudo systemctl start docker

# Verify
docker --version
```

**Command wrapping:**

```bash theme={null}
# 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:

```json config.json theme={null}
{
  "security": {
    "sandbox": {
      "backend": "none"
    }
  }
}
```

<Warning>
  Only use `"backend": "none"` for development or trusted environments. Rely on `autonomy` and `workspace_only` settings for safety.
</Warning>

**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

```json config.json theme={null}
{
  "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

```json config.json theme={null}
{
  "autonomy": {
    "allowed_commands": ["git", "npm", "python3"],
    "allowed_paths": ["/tmp", "~/projects"]
  }
}
```

**Wildcard:**

```json theme={null}
"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

```json config.json theme={null}
{
  "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:

```json config.json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

<Steps>
  <Step title="Gateway Pairing">
    6-digit one-time code required for API access.
  </Step>

  <Step title="Channel Allowlists">
    Empty allowlist denies all messages (explicit opt-in).
  </Step>

  <Step title="Workspace Scoping">
    Filesystem access restricted to workspace directory.
  </Step>

  <Step title="Sandbox Isolation">
    OS-level isolation via landlock/firejail/bubblewrap/docker.
  </Step>

  <Step title="Resource Limits">
    CPU, memory, disk, process limits enforced.
  </Step>

  <Step title="Audit Trail">
    Signed event log with configurable retention.
  </Step>
</Steps>

## Configuration Profiles

### Development (Relaxed)

```json config.json theme={null}
{
  "security": {
    "sandbox": { "backend": "none" }
  },
  "autonomy": {
    "level": "full",
    "workspace_only": true,
    "allowed_commands": ["*"]
  }
}
```

### Production (Strict)

```json config.json theme={null}
{
  "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)

```json config.json theme={null}
{
  "security": {
    "sandbox": { "backend": "landlock" }
  },
  "autonomy": {
    "level": "restricted",
    "workspace_only": true,
    "allowed_commands": [],
    "max_actions_per_hour": 5
  },
  "runtime": {
    "kind": "native"
  }
}
```

## Troubleshooting

### Sandbox Not Available

```bash theme={null}
# 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

```bash theme={null}
# 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:

```json theme={null}
"allowed_commands": ["*"]  // Allow all
```

Or add specific command:

```json theme={null}
"allowed_commands": ["git", "npm", "your-command"]
```

### Docker Network Issues

Change network mode:

```json theme={null}
"runtime": {
  "docker": {
    "network": "bridge"  // From "none"
  }
}
```

### Landlock Not Detected

Verify kernel support:

```bash theme={null}
# 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

```json config.json theme={null}
{
  "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`:

```bash theme={null}
# 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:

```json theme={null}
"security": {
  "sandbox": {
    "backend": "firejail",
    "firejail_profile": "~/.nullclaw/firejail.profile"
  }
}
```

### Multi-Tier Sandboxing

Combine sandbox backends with tool-specific overrides:

```json config.json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Hardware Integration" href="/guides/hardware" icon="microchip">
    Connect Arduino, Raspberry Pi, STM32
  </Card>

  <Card title="AI Providers" href="/guides/providers" icon="brain">
    Configure OpenAI, Anthropic, OpenRouter
  </Card>
</CardGroup>