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:

{
  "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": []
  }
}

autonomy.level · 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

autonomy.workspace_only · boolean · default: "true"

Restrict file operations to the workspace directory (~/.nullclaw/workspace).

autonomy.max_actions_per_hour · number · default: "20"

Maximum number of tool actions per hour (rate limit).

autonomy.require_approval_for_medium_risk · boolean · default: "true"

Require user approval for medium-risk actions (file edits, API calls).

autonomy.block_high_risk_commands · boolean · default: "true"

Block high-risk commands entirely (rm -rf, sudo, etc.).

autonomy.allowed_commands · array

Explicit allowlist of shell commands (only used in restricted mode).

autonomy.allowed_paths · array

Additional directories the agent may access beyond the workspace.

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

Sandbox Configuration

Run shell commands in an isolated sandbox:

{
  "security": {
    "sandbox": {
      "enabled": null,
      "backend": "auto",
      "firejail_args": []
    }
  }
}

security.sandbox.enabled · boolean

Enable sandboxing for shell commands. null (default) enables sandbox if a backend is available.

security.sandbox.backend · 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)

security.sandbox.firejail_args · array

Additional arguments passed to Firejail (e.g., ["--net=none", "--private"]).

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:

{
  "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
    }
  }
}

security.resources.max_memory_mb · number · default: "512"

Maximum memory per command (MB).

security.resources.max_cpu_percent · number · default: "80"

Maximum CPU usage percent.

security.resources.max_disk_mb · number · default: "1024"

Maximum disk space for temp files (MB).

security.resources.max_cpu_time_seconds · number · default: "60"

Maximum CPU time per command (seconds).

security.resources.max_subprocesses · number · default: "10"

Maximum number of subprocesses.

Audit Logging

Track all agent actions:

{
  "security": {
    "audit": {
      "enabled": true,
      "log_path": "audit.log",
      "retention_days": 90,
      "max_size_mb": 100,
      "sign_events": false
    }
  }
}

security.audit.enabled · boolean · default: "true"

Enable audit logging.

security.audit.log_path · string · default: "audit.log"

Audit log file path (relative to ~/.nullclaw/).

security.audit.retention_days · number · default: "90"

Keep audit logs for this many days.

security.audit.max_size_mb · number · default: "100"

Maximum audit log file size before rotation (MB).

security.audit.sign_events · boolean · default: "false"

Cryptographically sign audit events (requires key setup).

Runtime Configuration

Configure the execution environment:

{
  "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
    }
  }
}

runtime.kind · string · default: "native"

Runtime adapter: native (host system), docker, wasm, or cloudflare.

runtime.docker.image · string · default: "alpine:3.20"

Docker image for containerized execution.

runtime.docker.network · string · default: "none"

Docker network mode: none (no network), bridge, or host.

runtime.docker.memory_limit_mb · number · default: "512"

Memory limit for Docker containers (MB).

runtime.docker.read_only_rootfs · boolean · default: "true"

Mount container root filesystem as read-only.

Tool-Level Security

Configure specific tool restrictions:

{
  "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"]
  }
}

tools.shell_timeout_secs · number · default: "60"

Timeout for shell commands (seconds).

tools.shell_max_output_bytes · number · default: "1048576"

Maximum shell output size (1 MB).

browser.enabled · boolean · default: "false"

Enable browser automation tools. Disabled by default.

browser.allowed_domains · array

Allowlist of domains the browser can access (empty = all domains blocked).

http_request.enabled · boolean · default: "false"

Enable HTTP request tools. Disabled by default.

http_request.allowed_domains · array

Allowlist of domains for HTTP requests (empty = all blocked).

Example: Paranoid Security

Maximum security configuration:

{
  "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:

{
  "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": []
  }
}

Autonomous mode disables most safety checks. Only use in trusted environments where the agent can’t cause harm.