Security Best Practices

Learn more about Mintlify

Enter your email to receive updates about new features and product releases.

Principle: Defense in Depth
Authentication
API Keys
Gateway Pairing
Channel Allowlists
Authorization
Autonomy Levels
Tool Allowlists
Validation
Command Filtering
Path Validation
Network Restrictions
Sandboxing
Landlock (Linux)
Process Limits
Timeout Enforcement
Monitoring
Audit Logging
Anomaly Detection
Rate Limiting
Network Security
TLS/HTTPS
Reverse Proxy
Firewall Rules
Secret Management
Environment Variables
Secret Rotation
Incident Response
Compliance
Data Retention
PII Handling
Security Checklist
Related

Follow these security best practices to deploy ZeroClaw safely in production.

Principle: Defense in Depth

ZeroClaw implements multiple security layers:

Authentication - Pairing codes, API keys, allowlists
Authorization - Autonomy levels, approval prompts
Validation - Command filtering, path checking
Sandboxing - Process isolation, resource limits
Monitoring - Audit logs, anomaly detection

Authentication

API Keys

Never commit API keys to version control.

Best practices:

# Store in environment variables, not config files
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Use secret management in production
# AWS Secrets Manager
aws secretsmanager get-secret-value --secret-id zeroclaw/anthropic-key

# HashiCorp Vault
vault kv get secret/zeroclaw/api-keys

Gateway Pairing

Always enable pairing for internet-exposed gateways:

[gateway]
require_pairing = true
pairing_code_length = 8
pairing_timeout_minutes = 5

Pairing workflow:

Start gateway

zeroclaw gateway

Generates one-time pairing code: AB12-CD34

Client pairs

curl -X POST http://localhost:3000/pair \
  -d '{"code": "AB12-CD34"}'

Returns session token.

Use token

curl http://localhost:3000/api/chat \
  -H "Authorization: Bearer <token>"

Channel Allowlists

Restrict who can interact with the agent:

# Telegram
[channels.telegram]
allowed_user_ids = [123456789, 987654321]

# Discord
[channels.discord]
allowed_user_ids = ["123456789012345678"]

# Email
[channels.email]
allowed_senders = ["[email protected]", "@company.com"]

# Slack
[channels.slack]
allowed_users = ["U123ABC", "U456DEF"]

Authorization

Autonomy Levels

Control tool execution permissions:

Supervised (Recommended)
Semi-autonomous
Autonomous

Requires human approval for all tool calls.

[agent]
autonomy_level = "supervised"

Use when:

Running untrusted code
High-risk operations
Learning agent behavior

Auto-approves safe tools, prompts for risky ones.

[agent]
autonomy_level = "semi-autonomous"

[security]
auto_approve_tools = ["file_read", "memory_recall"]
require_approval_tools = ["shell", "file_write"]

Full automation, no approval needed.

[agent]
autonomy_level = "autonomous"

Only use in sandboxed environments with strict security policies.

Tool Allowlists

Disable unused tools:

[security]
shell_enabled = true
file_write_enabled = true
browser_enabled = false  # Disable if not needed

Validation

Command Filtering

Block dangerous shell commands:

[security]
blocked_commands = [
    # Destructive operations
    "rm -rf /",
    "mkfs",
    "dd if=",
    "format",
    
    # System modification
    "chmod 777",
    "chown root",
    
    # Network attacks
    "nmap",
    "tcpdump",
    
    # Crypto mining
    "xmrig",
    "cgminer"
]

Path Validation

Enforce workspace boundaries:

[security]
workspace_path = "/var/zeroclaw/workspace"

# Block access to sensitive directories
blocked_paths = [
    "/etc",
    "/sys",
    "/proc",
    "~/.ssh",
    "~/.aws"
]

Network Restrictions

Limit outbound connections:

[security]
allowed_domains = [
    "*.github.com",
    "api.anthropic.com",
    "api.openai.com"
]

blocked_ips = [
    "127.0.0.0/8",      # Localhost
    "10.0.0.0/8",       # Private
    "172.16.0.0/12",    # Private
    "192.168.0.0/16"    # Private
]

Sandboxing

Landlock (Linux)

Filesystem sandboxing with Landlock LSM:

# Build with Landlock support
cargo build --features sandbox-landlock

[security.sandboxing]
landlock_enabled = true
allowed_read_paths = ["/usr", "/lib", "$WORKSPACE"]
allowed_write_paths = ["$WORKSPACE", "/tmp"]

Process Limits

Prevent resource exhaustion:

[runtime]
max_memory_mb = 512
max_cpu_percent = 80
max_processes = 10
max_file_descriptors = 1024

Timeout Enforcement

Limit execution time:

[tools]
shell_timeout_seconds = 60
browser_timeout_seconds = 30
file_operation_timeout_seconds = 10

Monitoring

Audit Logging

Enable comprehensive audit logs:

[security.audit]
enabled = true
log_tool_calls = true
log_security_events = true
log_path = "~/.zeroclaw/audit.log"

Audit log format:

{
  "timestamp": "2026-03-03T12:00:00Z",
  "event_type": "tool_call",
  "tool": "shell",
  "args": {"command": "ls -la"},
  "result": "success",
  "user": "telegram:123456789",
  "session_id": "abc123"
}

Anomaly Detection

Monitor for unusual behavior:

[security.anomaly_detection]
enabled = true
max_failed_commands_per_hour = 10
max_sensitive_file_access_per_hour = 5
alert_on_blocked_command = true

Rate Limiting

Prevent abuse:

[security]
max_actions_per_hour = 100
max_actions_per_day = 1000
rate_limit_per_minute = 20

Network Security

TLS/HTTPS

Always use TLS for public endpoints:

[gateway]
tls_enabled = true
tls_cert_path = "/etc/zeroclaw/cert.pem"
tls_key_path = "/etc/zeroclaw/key.pem"

Generate self-signed cert for testing:

openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout key.pem -out cert.pem -days 365

Reverse Proxy

Use nginx or Caddy in front of gateway:

server {
    listen 443 ssl http2;
    server_name zeroclaw.example.com;
    
    ssl_certificate /etc/letsencrypt/live/zeroclaw.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/zeroclaw.example.com/privkey.pem;
    
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Firewall Rules

Restrict access to gateway:

# Allow only from specific IPs
sudo ufw allow from 203.0.113.0/24 to any port 3000

# Deny all other inbound
sudo ufw deny 3000

Secret Management

Environment Variables

Never hardcode secrets:

# ❌ DON'T: Store in config
[providers.anthropic]
api_key = "sk-ant-..."

# ✅ DO: Use environment variables
export ANTHROPIC_API_KEY="sk-ant-..."

Secret Rotation

Rotate API keys regularly:

Generate new key

Create new key in provider dashboard

Update environment

export ANTHROPIC_API_KEY="sk-ant-new-..."

Restart service

zeroclaw service restart

Verify

zeroclaw status

Revoke old key

Delete old key from provider dashboard

Incident Response

When security incidents occur:

Isolate

Stop the affected service:

zeroclaw service stop

Investigate

Review audit logs:

cat ~/.zeroclaw/audit.log | grep "blocked\|failed"

Remediate

Revoke compromised credentials
Update security policies
Patch vulnerabilities

Restore

Restart with updated configuration:

zeroclaw doctor
zeroclaw service start

Document

Record incident in security log

Compliance

Data Retention

Configure retention policies:

[memory]
retention_days = 90
auto_delete_old_entries = true

[security.audit]
log_retention_days = 365

PII Handling

Redact sensitive information:

[security]
redact_pii = true
pii_patterns = [
    "\\b\\d{3}-\\d{2}-\\d{4}\\b",  # SSN
    "\\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}\\b"  # Email
]

Security Checklist

Before deploying to production:

Troubleshooting

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Getting Started

Core Concepts

Guides

Operations

Security Best Practices

Principle: Defense in Depth

Authentication

API Keys

Gateway Pairing

Channel Allowlists

Authorization

Autonomy Levels

Tool Allowlists

Validation

Command Filtering

Path Validation

Network Restrictions

Sandboxing

Landlock (Linux)

Process Limits

Timeout Enforcement

Monitoring

Audit Logging

Anomaly Detection

Rate Limiting

Network Security

TLS/HTTPS

Reverse Proxy

Firewall Rules

Secret Management

Environment Variables

Secret Rotation

Incident Response

Compliance

Data Retention

PII Handling

Security Checklist

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Operations

​Principle: Defense in Depth

​Authentication

​API Keys

​Gateway Pairing

​Channel Allowlists

​Authorization

​Autonomy Levels

​Tool Allowlists

​Validation

​Command Filtering

​Path Validation

​Network Restrictions

​Sandboxing

​Landlock (Linux)

​Process Limits

​Timeout Enforcement

​Monitoring

​Audit Logging

​Anomaly Detection

​Rate Limiting

​Network Security

​TLS/HTTPS

​Reverse Proxy

​Firewall Rules

​Secret Management

​Environment Variables

​Secret Rotation

​Incident Response

​Compliance

​Data Retention

​PII Handling

​Security Checklist

​Related

Build docs developers (and LLMs) love

Principle: Defense in Depth

Authentication

API Keys

Gateway Pairing

Channel Allowlists

Authorization

Autonomy Levels

Tool Allowlists

Validation

Command Filtering

Path Validation

Network Restrictions

Sandboxing

Landlock (Linux)

Process Limits

Timeout Enforcement

Monitoring

Audit Logging

Anomaly Detection

Rate Limiting

Network Security

TLS/HTTPS

Reverse Proxy

Firewall Rules

Secret Management

Environment Variables

Secret Rotation

Incident Response

Compliance

Data Retention

PII Handling

Security Checklist

Related