Skip to main content
Nanobot provides multiple security layers to control access and restrict agent capabilities. This guide covers all security-related configuration options.

​
Access Control

Access control restricts who can interact with your bot across different channels.

​
Channel-Level Access Control

Each channel has an allowFrom field that controls which users can interact:
​
channels.{channel}.allowFrom
array
default:[]
Whitelist of user identifiers. Behavior depends on nanobot version:
  • v0.1.4.post3 and earlier: Empty array = allow all users
  • Source / newer versions: Empty array = deny all users; use ["*"] to allow all
Breaking Change: In versions after v0.1.4.post3 (including building from source), an empty allowFrom denies all access by default. To allow all users, explicitly set "allowFrom": ["*"].

​
Examples by Channel

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "...",
      "allowFrom": ["@username", "123456789"]
    }
  }
}

​
Workspace Sandboxing

Restrict all file and shell operations to the agent’s workspace directory.
​
tools.restrictToWorkspace
boolean
default:false
When true, restricts all agent tools to the workspace directory:
  • File read/write/edit operations
  • Directory listings
  • Shell command execution (cwd set to workspace)
Prevents path traversal attacks and unauthorized file access.
Workspace Sandboxing
{
  "tools": {
    "restrictToWorkspace": true
  },
  "agents": {
    "defaults": {
      "workspace": "~/.nanobot/workspace"
    }
  }
}
When enabled:
  • Agent cannot read files outside workspace
  • Agent cannot write files outside workspace
  • Shell commands run with workspace as working directory
  • Path traversal attempts (e.g. ../../../etc/passwd) are blocked
Production Recommendation: Always enable restrictToWorkspace: true for production deployments to prevent unauthorized access.

​
Group/Channel Policies

Control how the bot responds in group chats and channels.

​
Slack Group Policy

​
channels.slack.groupPolicy
string
default:"mention"
How to respond in group channels:
  • "mention" — Only respond when @mentioned
  • "open" — Respond to all messages
  • "allowlist" — Only respond in specific channels
​
channels.slack.groupAllowFrom
array
default:[]
Allowed channel IDs (used when groupPolicy is "allowlist").
Slack Group Policies
{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["C01234ABCDE"]
    }
  }
}

​
Discord Group Policy

​
channels.discord.groupPolicy
string
default:"mention"
How to respond in Discord servers:
  • "mention" — Only respond when @mentioned (default)
  • "open" — Respond to all messages
Discord Group Policy
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "...",
      "allowFrom": ["123456789012345678"],
      "groupPolicy": "mention"
    }
  }
}

​
Matrix Room Policy

​
channels.matrix.groupPolicy
string
default:"open"
How to respond in Matrix rooms:
  • "open" — Respond to all messages (default)
  • "mention" — Only respond when mentioned
  • "allowlist" — Only respond in allowed rooms
​
channels.matrix.groupAllowFrom
array
default:[]
Allowed room IDs (used when groupPolicy is "allowlist").
​
channels.matrix.allowRoomMentions
boolean
default:false
Accept @room mentions in mention mode (broadcasts to all room members).
Matrix Room Policy
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@bot:matrix.org",
      "accessToken": "...",
      "groupPolicy": "mention",
      "allowRoomMentions": false
    }
  }
}

​
Tool Security

​
Shell Execution

​
tools.exec.timeout
integer
default:60
Maximum execution time for shell commands (seconds). Prevents runaway processes.
​
tools.exec.pathAppend
string
Extra directories to append to PATH environment variable. Use this to grant access to system utilities (e.g. /usr/sbin for ufw firewall commands).
Shell Execution Limits
{
  "tools": {
    "exec": {
      "timeout": 30,
      "pathAppend": "/usr/sbin"
    }
  }
}

​
MCP Tool Timeouts

​
tools.mcpServers.{name}.toolTimeout
integer
default:30
Timeout in seconds for MCP tool calls. Prevents hanging tool operations.
MCP Timeouts
{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
        "toolTimeout": 30
      },
      "slow-api": {
        "url": "https://api.example.com/mcp/",
        "toolTimeout": 120
      }
    }
  }
}

​
Email Security

​
channels.email.consentGranted
boolean
default:false
required
Explicit consent flag required to enable email access. Must be true for the email channel to function.
​
channels.email.autoReplyEnabled
boolean
default:true
If false, the bot reads emails but doesn’t send automatic replies. Useful for monitoring or analysis mode.
​
channels.email.maxBodyChars
integer
default:12000
Maximum email body characters to process. Prevents processing of extremely large emails.
Email Security
{
  "channels": {
    "email": {
      "enabled": true,
      "consentGranted": true,
      "imapHost": "imap.gmail.com",
      "smtpHost": "smtp.gmail.com",
      "autoReplyEnabled": false,
      "maxBodyChars": 8000,
      "allowFrom": ["[email protected]"]
    }
  }
}

​
WhatsApp Bridge Security

​
channels.whatsapp.bridgeToken
string
Shared token for WhatsApp bridge authentication. Recommended for production.
WhatsApp Bridge Token
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "bridgeUrl": "ws://localhost:3001",
      "bridgeToken": "your-secret-token",
      "allowFrom": ["+1234567890"]
    }
  }
}

​
Matrix E2EE

​
channels.matrix.e2eeEnabled
boolean
default:true
Enable end-to-end encryption support. When enabled, the bot can participate in encrypted rooms.
​
channels.matrix.deviceId
string
required
Stable device ID needed to persist E2EE session state across restarts. Without this, the bot loses access to encrypted messages after restart.
​
channels.matrix.maxMediaBytes
integer
default:20971520
Maximum attachment size in bytes (default: 20MB). Set to 0 to block all media.
Matrix E2EE
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@bot:matrix.org",
      "accessToken": "...",
      "deviceId": "NANOBOT01",
      "e2eeEnabled": true,
      "maxMediaBytes": 10485760
    }
  }
}
Important: Keep a persistent matrix-store directory and stable deviceId — encrypted session state is lost if these change across restarts.

​
Complete Security Configuration

Example production configuration with all security features enabled: 
{
  "agents": {
    "defaults": {
      "workspace": "~/.nanobot/workspace",
      "model": "anthropic/claude-opus-4-5"
    }
  },
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-xxx"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "...",
      "allowFrom": ["@admin"],
      "replyToMessage": true
    },
    "discord": {
      "enabled": true,
      "token": "...",
      "allowFrom": ["123456789012345678"],
      "groupPolicy": "mention"
    },
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "allowFrom": ["U01234ABCDE"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["C01234ABCDE"],
      "dm": {
        "enabled": true,
        "policy": "allowlist",
        "allowFrom": ["U01234ABCDE"]
      }
    },
    "email": {
      "enabled": true,
      "consentGranted": true,
      "imapHost": "imap.gmail.com",
      "smtpHost": "smtp.gmail.com",
      "imapUsername": "[email protected]",
      "imapPassword": "...",
      "smtpUsername": "[email protected]",
      "smtpPassword": "...",
      "fromAddress": "[email protected]",
      "allowFrom": ["[email protected]"],
      "autoReplyEnabled": true,
      "maxBodyChars": 8000
    },
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@bot:matrix.org",
      "accessToken": "...",
      "deviceId": "NANOBOT01",
      "e2eeEnabled": true,
      "allowFrom": ["@admin:matrix.org"],
      "groupPolicy": "mention",
      "maxMediaBytes": 10485760
    }
  },
  "tools": {
    "restrictToWorkspace": true,
    "exec": {
      "timeout": 30
    },
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/.nanobot/workspace"],
        "toolTimeout": 30
      }
    }
  },
  "gateway": {
    "host": "127.0.0.1",
    "port": 18790
  }
}

​
Security Checklist

  • Enable tools.restrictToWorkspace: true
  • Configure allowFrom for all enabled channels
  • Set appropriate groupPolicy for multi-user channels
  • Use strong API keys and rotate them regularly
  • Set gateway.host: "127.0.0.1" if not exposing publicly
  • Configure tool timeouts to prevent resource exhaustion
  • Enable E2EE for Matrix if handling sensitive data
  • Use bridge tokens for WhatsApp connections
  • Set email consent flag explicitly
  • Review and minimize MCP server permissions
  • Use separate API keys for dev/prod
  • Set restrictive allowFrom even in dev
  • Test access control with unauthorized users
  • Verify workspace sandboxing blocks escapes
  • Test tool timeouts with slow operations
  • Monitor logs for security warnings
  • Use groupPolicy: "mention" or "allowlist"
  • Configure separate DM and group policies
  • Maintain user allowlists per channel
  • Document user access procedures
  • Audit access logs regularly

​
Best Practices

Principle of Least Privilege

Grant only the minimum permissions needed:
  • Use restrictToWorkspace in production
  • Set narrow allowFrom lists
  • Prefer "mention" policy over "open" in groups
  • Limit MCP server access to required directories

Defense in Depth

Use multiple security layers:
  • Channel-level access control
  • Workspace sandboxing
  • Tool execution timeouts
  • Network isolation (firewall rules)
  • Regular credential rotation

Audit and Monitor

Track security-relevant events:
  • Review gateway logs regularly
  • Monitor for unauthorized access attempts
  • Track tool execution patterns
  • Audit file access within workspace
  • Set up alerts for suspicious activity

​
Next Steps

Configuration Overview

Return to configuration overview

Providers

Configure LLM provider authentication

Build docs developers (and LLMs) love

Get started for freeTalk to us