This guide covers security best practices and hardening measures for MicroClaw deployments.
MicroClaw includes several security features:
The sandbox mode runs bash commands in isolated Docker containers:
sandbox:
mode: "all" # Enable for all bash commands
backend: "auto" # Auto-detect Docker
security_profile: "hardened"
image: "ubuntu:25.10"
container_prefix: "microclaw-sandbox"
no_network: true # Disable network access in sandbox
require_runtime: false
| Profile | Docker Options | Use Case |
|---|---|---|
| hardened | --cap-drop ALL --security-opt no-new-privileges |
Production, untrusted input |
| standard | Docker default capabilities | General use |
| privileged | --privileged |
Debugging only |
microclaw doctor sandbox
⚠️ Important: Sandbox mode provides isolation but is not a complete security boundary. Always:
Store API keys in environment variables rather than configuration files:
export MICROCLAW_API_KEY="sk-ant-..."
export TELEGRAM_BOT_TOKEN="..."
microclaw start
For Ansible deployments, use vault encryption:
ansible-vault encrypt secrets/vault.yml
For Docker deployments, use Docker secrets:
services:
microclaw:
image: microclaw/microclaw:latest
secrets:
- api_key
- telegram_token
secrets:
api_key:
external: true
telegram_token:
external: true
Ensure configuration files have restrictive permissions:
chmod 600 ~/.microclaw/microclaw.config.yaml
chmod 700 ~/.microclaw/
chown -R microclaw:microclaw ~/.microclaw/
Designate specific chats as “control chats” with elevated permissions:
control_chat_ids:
- "telegram:123456789"
- "discord:987654321"
Control chats can:
Non-control chats:
channels:
telegram:
default_account: "main"
accounts:
main:
bot_token: "..."
# Only respond to specific chats
allowed_chats:
- "-1001234567890"
# Only respond to mentions in groups
mention_only: true
# Each chat has isolated working directory (recommended)
working_dir_isolation: "chat"
# All chats share the same working directory
working_dir_isolation: "shared"
tools:
file:
allowed_paths:
- "~/.microclaw/working_dir"
# Deny access to sensitive directories
denied_paths:
- "/etc"
- "/root"
- "/home"
tools:
bash:
# Enable sandbox (required for security)
sandbox: true
# Command timeout in seconds
timeout: 300
# Whitelist allowed commands
allowed_commands:
- ls
- cat
- grep
- find
- pwd
- head
- tail
# Deny dangerous commands
denied_commands:
- rm
- sudo
- su
- chmod
- chown
- wget
- curl
tools:
web:
# Restrict domains (optional)
allowed_domains:
- "github.com"
- "stackoverflow.com"
- "docs.python.org"
# Block internal network access
block_internal: true
# User agent for identification
user_agent: "MicroClaw/1.0"
Enable confirmation for high-risk operations:
tools:
require_confirmation:
- bash
- write_file
- delete_file
sandbox:
no_network: true
Allow only necessary outbound connections:
# Allow LLM API (example: Anthropic)
ufw allow out to api.anthropic.com port 443
# Allow Telegram API
ufw allow out to api.telegram.org port 443
# Deny all other outbound (optional, advanced)
# ufw default deny outgoing
web:
enabled: true
host: "127.0.0.1" # Only allow localhost
port: 10961
For remote access, use SSH tunneling:
ssh -L 10961:127.0.0.1:10961 user@server
microclaw web password-generate
Use a reverse proxy with TLS termination:
Nginx Configuration:
server {
listen 443 ssl;
server_name microclaw.example.com;
ssl_certificate /etc/letsencrypt/live/microclaw.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/microclaw.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:10961;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
# Redirect HTTP to HTTPS
server {
listen 80;
server_name microclaw.example.com;
return 301 https://$server_name$request_uri;
}
web:
session_timeout: 30 # Minutes
memory:
# Isolate memory per chat
isolation: "chat"
# Minimum confidence for memory injection
min_confidence: 0.7
# Archive old memories
archive_threshold_days: 30
Avoid storing sensitive data in memory:
memory:
# Patterns to exclude from memory
exclude_patterns:
- "password"
- "api_key"
- "token"
- "secret"
Only enable trusted MCP servers:
{
"mcpServers": {
"filesystem": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
}
}
}
For remote MCP servers, use network isolation:
# Run MCP servers in isolated network
# Use firewall rules to restrict access
logging:
level: "info"
format: "json" # Easier for log analysis
file: "~/.microclaw/runtime/logs/microclaw.log"
# Watch for failed tool executions
tail -f ~/.microclaw/runtime/logs/microclaw.log | grep -i "error\|failed"
# Monitor sandbox violations
tail -f ~/.microclaw/runtime/logs/microclaw.log | grep -i "sandbox"
logging:
max_file_size_mb: 100
retention_count: 10
# Create dedicated user
sudo useradd -r -s /bin/false microclaw
# Set ownership
sudo chown -R microclaw:microclaw ~/.microclaw/
Create /etc/systemd/system/microclaw.service:
[Unit]
Description=MicroClaw AI Agent
After=network.target
[Service]
Type=simple
User=microclaw
Group=microclaw
WorkingDirectory=/home/microclaw
ExecStart=/home/microclaw/.microclaw/bin/microclaw start
Restart=always
# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
PrivateDevices=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
RestrictNamespaces=true
RestrictRealtime=true
RestrictSUIDSGID=true
MemoryDenyWriteExecute=true
LockPersonality=true
# Allow write access to data directory
ReadWritePaths=/home/microclaw/.microclaw
# Allow Docker socket for sandbox mode (if needed)
# ReadWritePaths=/var/run/docker.sock
[Install]
WantedBy=multi-user.target
[Service]
# Memory limit
MemoryLimit=2G
# CPU limit
CPUQuota=200%
# File descriptor limit
LimitNOFILE=65536
# Process limit
LimitNPROC=64
# Create encrypted backup
tar -czf - ~/.microclaw | openssl enc -aes-256-cbc -salt -out microclaw-backup.tar.gz.enc
# Restore from encrypted backup
openssl enc -aes-256-cbc -d -in microclaw-backup.tar.gz.enc | tar -xzf -
# Ansible backup configuration
microclaw_backup_dir: "/var/backups/microclaw"
microclaw_backup_permissions: "0700"
microclaw_backup_encryption: true
# Stop service
microclaw gateway stop
# Or systemd
sudo systemctl stop microclaw
# Last 1000 lines
tail -n 1000 ~/.microclaw/runtime/logs/microclaw.log
# Search for specific events
grep -i "error\|failed\|denied" ~/.microclaw/runtime/logs/microclaw.log
Any questions?
Feel free to contact us. Find all contact information on our contact page.