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

> Configure sandboxing, resource limits, and autonomy settings

NullClaw provides multiple layers of security controls to safely execute agent actions. Configure sandboxing, resource limits, and autonomy policies to match your risk tolerance.

## Autonomy Level

Control how much independence the agent has:

```json theme={null}
{
  "autonomy": {
    "level": "supervised",
    "workspace_only": true,
    "max_actions_per_hour": 20,
    "require_approval_for_medium_risk": true,
    "block_high_risk_commands": true,
    "allowed_commands": [],
    "allowed_paths": []
  }
}
```

<ParamField path="autonomy.level" type="string" default="supervised">
  Autonomy level:

  * `supervised` — Require approval for medium/high risk actions (default)
  * `autonomous` — Execute all allowed actions without approval
  * `restricted` — Only execute explicitly allowed commands
</ParamField>

<ParamField path="autonomy.workspace_only" type="boolean" default="true">
  Restrict file operations to the workspace directory (`~/.nullclaw/workspace`).
</ParamField>

<ParamField path="autonomy.max_actions_per_hour" type="number" default="20">
  Maximum number of tool actions per hour (rate limit).
</ParamField>

<ParamField path="autonomy.require_approval_for_medium_risk" type="boolean" default="true">
  Require user approval for medium-risk actions (file edits, API calls).
</ParamField>

<ParamField path="autonomy.block_high_risk_commands" type="boolean" default="true">
  Block high-risk commands entirely (rm -rf, sudo, etc.).
</ParamField>

<ParamField path="autonomy.allowed_commands" type="array">
  Explicit allowlist of shell commands (only used in `restricted` mode).
</ParamField>

<ParamField path="autonomy.allowed_paths" type="array">
  Additional directories the agent may access beyond the workspace.
</ParamField>

<Warning>
  Setting `workspace_only: false` allows the agent to read/write anywhere on the filesystem. Only disable this if you trust the agent completely.
</Warning>

## Sandbox Configuration

Run shell commands in an isolated sandbox:

```json theme={null}
{
  "security": {
    "sandbox": {
      "enabled": null,
      "backend": "auto",
      "firejail_args": []
    }
  }
}
```

<ParamField path="security.sandbox.enabled" type="boolean">
  Enable sandboxing for shell commands. `null` (default) enables sandbox if a backend is available.
</ParamField>

<ParamField path="security.sandbox.backend" type="string" default="auto">
  Sandbox backend:

  * `auto` — Auto-detect best available backend
  * `landlock` — Linux Landlock LSM (kernel 5.13+)
  * `firejail` — Firejail sandbox wrapper
  * `bubblewrap` — Bubblewrap (bwrap) sandbox
  * `docker` — Run commands in Docker containers
  * `none` — No sandboxing (unsafe)
</ParamField>

<ParamField path="security.sandbox.firejail_args" type="array">
  Additional arguments passed to Firejail (e.g., `["--net=none", "--private"]`).
</ParamField>

### Sandbox Backend Comparison

| Backend        | Platform    | Isolation               | Setup                    |
| -------------- | ----------- | ----------------------- | ------------------------ |
| **landlock**   | Linux 5.13+ | Kernel-level filesystem | Built-in (no setup)      |
| **firejail**   | Linux       | Namespace + seccomp     | `apt install firejail`   |
| **bubblewrap** | Linux       | Namespace isolation     | `apt install bubblewrap` |
| **docker**     | Linux/macOS | Full container          | Docker installed         |
| **none**       | Any         | No isolation            | N/A                      |

## Resource Limits

Constrain CPU, memory, and disk usage:

```json theme={null}
{
  "security": {
    "resources": {
      "max_memory_mb": 512,
      "max_cpu_percent": 80,
      "max_disk_mb": 1024,
      "max_cpu_time_seconds": 60,
      "max_subprocesses": 10,
      "memory_monitoring": true
    }
  }
}
```

<ParamField path="security.resources.max_memory_mb" type="number" default="512">
  Maximum memory per command (MB).
</ParamField>

<ParamField path="security.resources.max_cpu_percent" type="number" default="80">
  Maximum CPU usage percent.
</ParamField>

<ParamField path="security.resources.max_disk_mb" type="number" default="1024">
  Maximum disk space for temp files (MB).
</ParamField>

<ParamField path="security.resources.max_cpu_time_seconds" type="number" default="60">
  Maximum CPU time per command (seconds).
</ParamField>

<ParamField path="security.resources.max_subprocesses" type="number" default="10">
  Maximum number of subprocesses.
</ParamField>

## Audit Logging

Track all agent actions:

```json theme={null}
{
  "security": {
    "audit": {
      "enabled": true,
      "log_path": "audit.log",
      "retention_days": 90,
      "max_size_mb": 100,
      "sign_events": false
    }
  }
}
```

<ParamField path="security.audit.enabled" type="boolean" default="true">
  Enable audit logging.
</ParamField>

<ParamField path="security.audit.log_path" type="string" default="audit.log">
  Audit log file path (relative to `~/.nullclaw/`).
</ParamField>

<ParamField path="security.audit.retention_days" type="number" default="90">
  Keep audit logs for this many days.
</ParamField>

<ParamField path="security.audit.max_size_mb" type="number" default="100">
  Maximum audit log file size before rotation (MB).
</ParamField>

<ParamField path="security.audit.sign_events" type="boolean" default="false">
  Cryptographically sign audit events (requires key setup).
</ParamField>

## Runtime Configuration

Configure the execution environment:

```json theme={null}
{
  "runtime": {
    "kind": "native",
    "docker": {
      "image": "alpine:3.20",
      "network": "none",
      "memory_limit_mb": 512,
      "cpu_limit": 1.0,
      "read_only_rootfs": true,
      "mount_workspace": true
    }
  }
}
```

<ParamField path="runtime.kind" type="string" default="native">
  Runtime adapter: `native` (host system), `docker`, `wasm`, or `cloudflare`.
</ParamField>

<ParamField path="runtime.docker.image" type="string" default="alpine:3.20">
  Docker image for containerized execution.
</ParamField>

<ParamField path="runtime.docker.network" type="string" default="none">
  Docker network mode: `none` (no network), `bridge`, or `host`.
</ParamField>

<ParamField path="runtime.docker.memory_limit_mb" type="number" default="512">
  Memory limit for Docker containers (MB).
</ParamField>

<ParamField path="runtime.docker.read_only_rootfs" type="boolean" default="true">
  Mount container root filesystem as read-only.
</ParamField>

## Tool-Level Security

Configure specific tool restrictions:

```json theme={null}
{
  "tools": {
    "shell_timeout_secs": 60,
    "shell_max_output_bytes": 1048576,
    "max_file_size_bytes": 10485760,
    "web_fetch_max_chars": 100000
  },
  "browser": {
    "enabled": false,
    "allowed_domains": ["example.com", "trusted.org"]
  },
  "http_request": {
    "enabled": false,
    "allowed_domains": ["api.example.com"]
  }
}
```

<ParamField path="tools.shell_timeout_secs" type="number" default="60">
  Timeout for shell commands (seconds).
</ParamField>

<ParamField path="tools.shell_max_output_bytes" type="number" default="1048576">
  Maximum shell output size (1 MB).
</ParamField>

<ParamField path="browser.enabled" type="boolean" default="false">
  Enable browser automation tools. Disabled by default.
</ParamField>

<ParamField path="browser.allowed_domains" type="array">
  Allowlist of domains the browser can access (empty = all domains blocked).
</ParamField>

<ParamField path="http_request.enabled" type="boolean" default="false">
  Enable HTTP request tools. Disabled by default.
</ParamField>

<ParamField path="http_request.allowed_domains" type="array">
  Allowlist of domains for HTTP requests (empty = all blocked).
</ParamField>

## Example: Paranoid Security

Maximum security configuration:

```json theme={null}
{
  "autonomy": {
    "level": "supervised",
    "workspace_only": true,
    "max_actions_per_hour": 10,
    "require_approval_for_medium_risk": true,
    "block_high_risk_commands": true
  },
  "security": {
    "sandbox": {
      "enabled": true,
      "backend": "landlock"
    },
    "resources": {
      "max_memory_mb": 256,
      "max_cpu_percent": 50,
      "max_cpu_time_seconds": 30,
      "memory_monitoring": true
    },
    "audit": {
      "enabled": true,
      "sign_events": true,
      "retention_days": 365
    }
  },
  "runtime": {
    "kind": "docker",
    "docker": {
      "image": "alpine:3.20",
      "network": "none",
      "read_only_rootfs": true,
      "memory_limit_mb": 256
    }
  },
  "browser": {
    "enabled": false
  },
  "http_request": {
    "enabled": false
  }
}
```

## Example: Autonomous Mode

Trusted environment with minimal restrictions:

```json theme={null}
{
  "autonomy": {
    "level": "autonomous",
    "workspace_only": false,
    "max_actions_per_hour": 100,
    "require_approval_for_medium_risk": false,
    "block_high_risk_commands": false,
    "allowed_paths": ["/home/user/projects"]
  },
  "security": {
    "sandbox": {
      "backend": "none"
    },
    "audit": {
      "enabled": true
    }
  },
  "browser": {
    "enabled": true,
    "allowed_domains": []
  },
  "http_request": {
    "enabled": true,
    "allowed_domains": []
  }
}
```

<Warning>
  Autonomous mode disables most safety checks. Only use in trusted environments where the agent can't cause harm.
</Warning>