Security Configuration

Overview

OrcBot provides multiple layers of security controls including safe mode, command filtering, plugin restrictions, and policy-based configuration management.

Security Modes

Safe Mode

boolean

default:false

Enable safe mode to disable command execution and skill creation.Policy: LOCKED - Security-critical configuration. Agent cannot modify.When enabled:

run_command skill is blocked
create_custom_skill is blocked
Command-based operations are restricted
Plugin execution may be limited

safeMode: true  # Production-safe setting

Sudo Mode

boolean

default:false

Enable unrestricted access mode (bypasses command allow/deny lists).Policy: LOCKED - Security-critical configuration.

Use with extreme caution. Sudo mode removes safety guardrails and allows the agent to run any command, including destructive operations.

sudoMode: false  # Recommended for all deployments

Override Mode

boolean

default:false

Enable behavioral override mode that bypasses persona boundaries.Policy: LOCKED - Security-critical configuration.

Experimental feature. Override mode allows the agent to bypass its normal behavioral constraints.

overrideMode: false  # Keep disabled unless testing

Command Security

Command Allow List

array

Whitelist of allowed shell commands. Empty list means all commands are blocked (unless in sudo mode).Default includes common development tools:

commandAllowList:
  - npm
  - node
  - npx
  - git
  - python
  - pip
  - pip3
  - curl
  - wget
  - powershell
  - pwsh
  - bash
  - apt
  - apt-get
  - yum
  - brew
  - systemctl
  - service
  - cat
  - ls
  - dir
  - echo
  - mkdir
  - touch
  - cp
  - mv
  - grep
  - find
  - which
  - whoami
  - uname
  - hostname
  - orcbot

Command Deny List

array

Blacklist of denied commands. Takes precedence over allow list.Policy: LOCKED - Security-critical configuration.Default blocks destructive operations:

commandDenyList:
  - rm          # Remove files
  - rmdir       # Remove directories
  - del         # Windows delete
  - erase       # Windows erase
  - format      # Format disk
  - mkfs        # Make filesystem
  - dd          # Disk duplicator (dangerous)
  - shutdown    # Shutdown system
  - reboot      # Reboot system
  - poweroff    # Power off
  - reg         # Windows registry
  - diskpart    # Windows disk partitioning
  - netsh       # Windows network config

The deny list is enforced even in sudo mode to prevent accidental catastrophic operations.

Command Execution Settings

number

default:120000

Timeout for shell command execution in milliseconds (default: 2 minutes).Prevents runaway processes from consuming resources indefinitely.

number

default:1

Number of retries for failed commands.

string

Working directory for command execution. Defaults to current directory.

boolean

default:false

Automatically execute commands without confirmation.

Disable for production. Auto-execution bypasses human oversight.

Example: Lockdown Configuration

orcbot.config.yaml

# Maximum security configuration
safeMode: true
sudoMode: false
overrideMode: false

# Minimal command access
commandAllowList:
  - git
  - npm
  - node

# Comprehensive deny list
commandDenyList:
  - rm
  - rmdir
  - del
  - format
  - shutdown
  - reboot
  - dd
  - diskpart
  - reg
  - netsh

# Strict execution settings
autoExecuteCommands: false
commandTimeoutMs: 60000  # 1 minute max

Plugin Security

Plugin Allow List

array

default:[]

Whitelist of allowed plugins. Empty array means all plugins are allowed.

pluginAllowList:
  - stripe-payment
  - calendar-sync
  - custom-search

When pluginAllowList is non-empty, only plugins in the list can be loaded.

Plugin Deny List

array

default:[]

Blacklist of denied plugins. Takes precedence over allow list.

pluginDenyList:
  - experimental-plugin
  - untrusted-plugin

Plugin Health Monitoring

number

default:15

Interval for checking plugin health and triggering auto-repair.OrcBot automatically detects broken plugins and uses self_repair_skill to fix them.

Example: Plugin Security

orcbot.config.yaml

# Strict plugin control
pluginAllowList:
  - approved-plugin-1
  - approved-plugin-2

pluginDenyList:
  - dangerous-plugin
  - untested-plugin

# Frequent health checks
pluginHealthCheckIntervalMinutes: 10

Admin Permissions

object

Per-channel admin user allowlists. Admins have access to elevated commands and skills.Policy: LOCKED - Security-critical configuration.

adminUsers:
  telegram:
    - "123456789"      # Telegram user ID
  whatsapp:
    - "1234567890@s.whatsapp.net"  # WhatsApp JID
  discord:
    - "123456789012345678"  # Discord user ID
  slack:
    - "U0123456789"   # Slack user ID
  email:
    - "admin@example.com"  # Email address

Admin-Only Skills

These skills are restricted to admin users:

run_command

Execute shell commands on the host system.

create_custom_skill

Create executable TypeScript plugin skills.

manage_config

Modify configuration settings (subject to policy).

spawn_agent

Create worker agent processes.

delegate_task

Orchestrate tasks across multiple agents.

system_check

Verify system dependencies and commands.

self_repair_skill

Repair broken plugin code.

execute_typescript

Write and execute TypeScript scripts.

Non-admin users cannot execute admin-only skills. Attempts will be logged and blocked.

Configuration Policy

OrcBot uses a three-tier policy system to control which configuration options agents can modify:

Policy Levels

SAFE - Agent can modify

Safe configuration options that agents can modify autonomously to optimize performance:

modelName - Switch models for different tasks
llmProvider - Switch providers based on availability
memoryContextLimit - Adjust memory context
maxStepsPerAction - Adjust complexity limits
progressFeedbackEnabled - Control feedback verbosity
searchProviderOrder - Optimize search provider selection
Browser and diagnostic settings

Example:

# Agent can adjust these freely
modelName: gpt-4o          # SAFE
memoryContextLimit: 30     # SAFE
maxStepsPerAction: 40      # SAFE

APPROVAL - Requires approval

Sensitive options that agents can request to change but require human approval:

API keys (OpenAI, Google, Anthropic, etc.)
autonomyEnabled - Enable autonomous operation
autonomyInterval - Autonomy timing
skillRoutingRules - Skill selection rules

Example:

# Agent can request changes, human approves
openaiApiKey: sk-...       # APPROVAL
autonomyEnabled: true      # APPROVAL

Agents can view pending approvals with manage_config({ action: "pending" })

LOCKED - Agent cannot modify

Security-critical options that agents cannot modify at all:

Channel tokens (Telegram, Discord, Slack)
safeMode - Safe mode toggle
sudoMode - Sudo mode toggle
overrideMode - Override mode toggle
commandDenyList - Command blacklist
adminUsers - Admin permissions
AWS Bedrock credentials
enableSelfModification - Self-modification permission

Example:

# Agent cannot modify these at all
safeMode: true             # LOCKED
telegramToken: "..."       # LOCKED
adminUsers:                # LOCKED
  telegram: ["123456"]

Attempts to modify LOCKED config will be rejected with an error message.

Policy Usage

Agents use the manage_config skill to interact with configuration:

# View configuration by policy level
manage_config({ action: "show", detail: "policy" })

# Modify SAFE config (allowed)
manage_config({
  action: "set",
  key: "modelName",
  value: "gpt-4o",
  reason: "Code task benefits from GPT-4"
})

# Request APPROVAL config (requires human approval)
manage_config({
  action: "set",
  key: "openaiApiKey",
  value: "sk-new-key",
  reason: "API key rotation"
})

# View pending approvals
manage_config({ action: "pending" })

# Approve change (human only)
manage_config({ action: "approve", key: "openaiApiKey" })

API Key Management

Secure Storage

Never commit API keys to version control. Use environment variables or local config files that are .gitignored.

Use environment variables

Store API keys in .env files:

.env

OPENAI_API_KEY=sk-your-key-here
GOOGLE_API_KEY=your-google-key
ANTHROPIC_API_KEY=sk-ant-your-key
TELEGRAM_TOKEN=your-telegram-token

Restrict file permissions

chmod 600 .env
chmod 700 ~/.orcbot

Use key rotation

Regularly rotate API keys and update configuration:

# Generate new key, then update
orcbot config set openaiApiKey sk-new-key

Monitor usage

Enable token tracking to detect anomalies:

tokenUsagePath: ~/.orcbot/token-usage-summary.json
tokenLogPath: ~/.orcbot/token-usage.log

API Key Configuration

All API keys support environment variable fallback:

string

Policy: APPROVALEnvironment variable: OPENAI_API_KEY

string

Policy: APPROVALEnvironment variable: GOOGLE_API_KEY

string

Policy: APPROVALEnvironment variable: ANTHROPIC_API_KEY

string

Policy: APPROVALEnvironment variable: OPENROUTER_API_KEY

string

Policy: APPROVALEnvironment variable: NVIDIA_API_KEY

string

Policy: APPROVALEnvironment variable: SERPER_API_KEY

string

Policy: APPROVALEnvironment variable: BRAVE_SEARCH_API_KEY

string

2Captcha API key for solving CAPTCHAs.Environment variable: CAPTCHA_API_KEY

string

Policy: LOCKEDEnvironment variable: TELEGRAM_TOKEN

string

Policy: LOCKEDEnvironment variable: DISCORD_TOKEN

string

Policy: LOCKEDEnvironment variable: SLACK_BOT_TOKEN

string

Policy: LOCKEDEnvironment variable: BEDROCK_ACCESS_KEY_ID or AWS_ACCESS_KEY_ID

string

Policy: LOCKEDEnvironment variable: BEDROCK_SECRET_ACCESS_KEY or AWS_SECRET_ACCESS_KEY

Web Gateway Security

string

API key for authenticating gateway requests.Required for all API endpoints when configured:

curl -H "X-Api-Key: your-key" http://localhost:3100/api/status

Always set an API key for production deployments. Without it, anyone can access your agent’s API.

array

default:["*"]

CORS allowed origins for gateway API.

gatewayCorsOrigins:
  - https://yourdomain.com
  - https://app.yourdomain.com

number

default:3100

HTTP port for the web gateway.

string

default:"0.0.0.0"

Host address to bind the gateway server.

Use 127.0.0.1 to restrict to localhost only.

Tailscale (Recommended)

For remote access, use Tailscale instead of exposing the gateway publicly:

Install Tailscale

curl -fsSL https://tailscale.com/install.sh | sh

Connect to Tailnet

sudo tailscale up

Configure gateway for Tailnet

gatewayHost: 0.0.0.0  # Bind to all interfaces
gatewayPort: 3100
gatewayApiKey: your-secret-key  # Still use API key for defense-in-depth

Set Tailnet ACLs

Restrict access to specific devices/users in your Tailnet.

Tailscale provides a private mesh network so you don’t need to expose port 3100 publicly or use a reverse proxy.

Data Privacy

Local-First Architecture

OrcBot stores all data locally by default:

Memory - ~/.orcbot/memory.json
Journal - ~/.orcbot/JOURNAL.md
Learning - ~/.orcbot/LEARNING.md
User profiles - ~/.orcbot/USER.md
Action queue - ~/.orcbot/actions.json
Logs - ~/.orcbot/daemon.log

No data is uploaded to external services unless explicitly required by a skill (e.g., web search, LLM API calls).

Session Isolation

enum

default:"per-channel-peer"

Control conversation memory isolation:

main - Single global session (all users share memory)
per-peer - Separate session per user
per-channel-peer - Separate session per channel-user (recommended for privacy)

sessionScope: per-channel-peer  # Most private

Information Boundaries

OrcBot enforces information boundaries to prevent data leakage:

Non-admin tasks are blocked from accessing:
- Journal entries
- Learning notes
- Episodic context from other users
- Admin-specific memory
Per-channel isolation prevents cross-channel context leakage
Memory deduplication prevents duplicate sensitive data

Telemetry

boolean

default:true

Enable anonymous usage telemetry.Telemetry includes:

Version number
Anonymous installation ID
Uptime statistics
Error counts (no error content)

No user data, messages, or API keys are included in telemetry.

string

default:""

Telemetry endpoint URL (default: OrcBot telemetry service).

number

default:4000

Timeout for telemetry requests in milliseconds.

string

default:""

Authentication token for telemetry (if required by endpoint).

Disable Telemetry

orcbot.config.yaml

usagePingEnabled: false

Security Best Practices

Enable Safe Mode

Use safeMode: true in production to prevent command execution.

Restrict Commands

Carefully curate commandAllowList and commandDenyList.

Set Admin Users

Explicitly configure adminUsers per channel.

Secure API Keys

Use environment variables and restrict file permissions.

Use Tailscale

Access gateway via private mesh network instead of public internet.

Set Gateway API Key

Always configure gatewayApiKey for production.

Control Plugins

Use pluginAllowList and pluginDenyList to restrict plugins.

Isolate Sessions

Use sessionScope: per-channel-peer for privacy.

Production Security Template

orcbot.config.yaml

# Security Configuration for Production

# Core security modes
safeMode: true
sudoMode: false
overrideMode: false

# Command restrictions
commandAllowList:
  - git
  - npm
  - node
commandDenyList:
  - rm
  - shutdown
  - reboot
  - dd
autoExecuteCommands: false

# Plugin restrictions
pluginAllowList:
  - approved-plugin-1
pluginDenyList:
  - experimental-plugin

# Admin permissions
adminUsers:
  telegram:
    - "YOUR_TELEGRAM_USER_ID"

# Gateway security
gatewayApiKey: your-strong-random-key-here
gatewayHost: 0.0.0.0
gatewayPort: 3100
gatewayCorsOrigins:
  - https://yourdomain.com

# Privacy
sessionScope: per-channel-peer

# Telemetry (optional)
usagePingEnabled: false

Review and test security configuration before deploying to production. Test with non-admin users to verify restrictions are enforced.

​Overview

​Security Modes

​Safe Mode

​Sudo Mode

​Override Mode

​Command Security

​Command Allow List

​Command Deny List

​Command Execution Settings

​Example: Lockdown Configuration

​Plugin Security

​Plugin Allow List

​Plugin Deny List

​Plugin Health Monitoring

​Example: Plugin Security

​Admin Permissions

​Admin-Only Skills

run_command

create_custom_skill

manage_config

spawn_agent

delegate_task

system_check

self_repair_skill

execute_typescript

​Configuration Policy

​Policy Levels

​Policy Usage

​API Key Management

​Secure Storage

​API Key Configuration

​Web Gateway Security

​Tailscale (Recommended)

​Data Privacy

​Local-First Architecture

​Session Isolation

​Information Boundaries

​Telemetry

​Disable Telemetry

​Security Best Practices

Enable Safe Mode

Restrict Commands

Set Admin Users

Secure API Keys

Use Tailscale

Set Gateway API Key

Control Plugins

Isolate Sessions

​Production Security Template

Overview

Security Modes

Safe Mode

Sudo Mode

Override Mode

Command Security

Command Allow List

Command Deny List

Command Execution Settings

Example: Lockdown Configuration

Plugin Security

Plugin Allow List

Plugin Deny List

Plugin Health Monitoring

Example: Plugin Security

Admin Permissions

Admin-Only Skills

Configuration Policy

Policy Levels

Policy Usage

API Key Management

Secure Storage

API Key Configuration

Web Gateway Security

Tailscale (Recommended)

Data Privacy

Local-First Architecture

Session Isolation

Information Boundaries

Telemetry

Disable Telemetry

Security Best Practices

Production Security Template