Security - OrcBot

Overview

OrcBot provides multiple layers of security to protect your system, data, and users. This guide covers configuration options, access controls, and production best practices.

OrcBot has powerful capabilities including shell execution and file system access. Always run in safeMode initially and enable features incrementally.

Security Modes

Safe Mode

# orcbot.config.yaml
safeMode: true

Disabled Capabilities:

run_command - No shell execution
execute_typescript / execute_python_code - No code execution
write_file - No file writes
create_custom_skill - No plugin creation
manage_config (unsafe keys) - No API key modifications

Use Cases:

Testing new LLM providers
Public demos
Untrusted environments

Sudo Mode (Default)

safeMode: false

All skills enabled with guardrails:

Command allow/deny lists
Plugin security controls
Admin-only skills
Configuration policy (SAFE/APPROVAL/LOCKED)

Use Cases:

Personal assistant
Development environments
Trusted multi-user deployments

Override Mode

safeMode: false
autopilotNoQuestions: true
disableTerminationReview: true

Minimal guardrails for maximum autonomy.

Use with extreme caution. The agent can execute commands, modify files, and make network requests without additional checks.

Command Security

Allow/Deny Lists

# orcbot.config.yaml
commandAllowList:
  - npm
  - git
  - docker
  - ls
  - cat
  - grep

commandDenyList:
  - rm -rf
  - dd
  - mkfs
  - format
  - shutdown
  - reboot

How It Works:

Command Requested

Agent attempts run_command("rm -rf /tmp/file")

Parse Command

Extract base command: rm

Check Allow List

If commandAllowList is set and rm is not in it, reject.

Check Deny List

If rm -rf matches any pattern in commandDenyList, reject.

Execute or Block

If all checks pass, execute. Otherwise, return error.

Platform-Specific Commands

# Windows
commandDenyList:
  - del /F
  - rmdir /S
  - format

# Linux/macOS
commandDenyList:
  - rm -rf /
  - dd if=/dev/zero
  - :(){ :|:& };:

Plugin Security

Allow/Deny Lists

# orcbot.config.yaml
pluginAllowList:
  - stripe-payment
  - salesforce-sync
  - custom-analytics

pluginDenyList:
  - untested-plugin
  - experimental-*

Rules:

If pluginAllowList is set, only listed plugins load
Plugins in pluginDenyList are always blocked
Wildcards supported: experimental-*

Plugin Health Monitoring

pluginHealthCheckInterval: 30000  # 30 seconds

OrcBot automatically:

Detects plugin crashes
Attempts self_repair_skill for broken plugins
Disables plugins after 3 consecutive failures

Manual Plugin Management

# View plugin status
orcbot ui
# Navigate to Tools Manager

# Disable a plugin
orcbot push "Deactivate the experimental-plugin"

# Re-enable after fixes
orcbot push "Activate the experimental-plugin"

Admin Permissions

Configuring Admins

# orcbot.config.yaml
adminUsers:
  telegram:
    - "123456789"          # Telegram user ID
    - "@username"          # Telegram username
  discord:
    - "987654321098765432" # Discord user ID
  whatsapp:
    - "1234567890@s.whatsapp.net"

Finding your user ID:Telegram: Message the bot with /status - your ID is shown.Discord: Enable Developer Mode → Right-click your name → Copy ID.WhatsApp: Your ID is in the bot logs when you first message it.

Admin-Only Skills

These skills require admin permissions:

Skill	Reason
`run_command`	Shell execution can modify system
`execute_typescript`	Arbitrary code execution
`write_file` (outside workspace)	File system writes
`create_custom_skill`	Plugin creation
`manage_config` (APPROVAL keys)	API key changes
`spawn_agent`	Resource-intensive
`system_check`	Exposes system information

Non-Admin Behavior:

// Non-admin user requests:
{
  "skillName": "run_command",
  "command": "ls -la"
}

// Response:
{
  "error": "Skill 'run_command' requires admin privileges",
  "contactAdmin": true
}

Temporary Elevation

# Grant admin for specific session
temporaryAdmins:
  telegram:
    - userId: "123456789"
      expiresAt: "2024-03-15T00:00:00Z"

Configuration Policy

OrcBot uses a 3-tier policy system for agent-driven config management:

Policy Levels

SAFE
APPROVAL
LOCKED

Agent can modify autonomously.Examples:

modelName - Switch models for better performance
maxStepsPerAction - Increase for complex tasks
memoryContextLimit - Expand for large contexts

No approval required.

Agent can request changes, human must approve.Examples:

openaiApiKey - API key rotation
telegramToken - Channel credentials
adminUsers - Permission changes

Changes queue for approval.

Agent cannot modify under any circumstances.Examples:

safeMode - Security setting
commandDenyList - Security controls
pluginDenyList - Plugin restrictions

Only editable via config file or TUI.

Approving Config Changes

# View pending changes
orcbot push "Show pending config approvals"

# Approve a change
orcbot push "Approve openaiApiKey change"

# Reject a change
orcbot push "Reject adminUsers change"

API Key Management

Secure Storage

Use Environment Variables

export OPENAI_API_KEY="sk-..."
export TELEGRAM_TOKEN="123..."

OrcBot reads from environment first, then config file.

Restrict File Permissions

chmod 600 ~/.orcbot/orcbot.config.yaml

Only the owner can read the config file.

Use Secrets Manager (Production)

For cloud deployments, use AWS Secrets Manager, HashiCorp Vault, or similar.Load secrets at runtime:

// Custom loader
const secrets = await loadFromVault();
config.openaiApiKey = secrets.OPENAI_API_KEY;

Key Rotation

# Old key in config
openaiApiKey: sk-old-key

# Agent requests rotation
# (via manage_config skill)

# Approve in TUI or CLI
# New key becomes active
openaiApiKey: sk-new-key

Never commit API keys to version control. Use .gitignore for orcbot.config.yaml.

Web Gateway Security

API Key Authentication

# orcbot.config.yaml
gatewayApiKey: your-secret-key-here

Clients must include the key in requests:

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

CORS Configuration

gatewayCorsOrigins:
  - https://app.example.com
  - https://dashboard.example.com

Default: ["*"] (allow all origins) Production: Restrict to your frontend domains only.

HTTPS via Reverse Proxy

# nginx.conf
server {
    listen 443 ssl;
    server_name bot.example.com;
    
    ssl_certificate /etc/letsencrypt/live/bot.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/bot.example.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:3100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Tailscale Private Network

Install Tailscale

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

Authenticate

sudo tailscale up

Configure Gateway

gatewayHost: 0.0.0.0  # Listen on all interfaces
gatewayPort: 3100

Access via Tailscale IP

curl http://100.x.y.z:3100/api/status

Only Tailnet members can reach the gateway.

Data Privacy

Local-First Architecture

All data stays on your machine:

Memory - ~/.orcbot/memory/
Logs - ~/.orcbot/logs/
Profiles - ~/.orcbot/profiles/
Config - ~/.orcbot/orcbot.config.yaml

External Calls:

LLM API (OpenAI, Google, etc.) - Only when processing tasks
Web searches - Only when web_search skill is used
Channel APIs (Telegram, Discord) - Only for message delivery

Session Isolation

memoryThreadMode: per-channel-peer

Options:

main - Single global context (all users share memory)
per-peer - Separate context per user (across all channels)
per-channel-peer - Separate context per user per channel

Recommendation: Use per-channel-peer for multi-user deployments.

Information Boundaries

Non-admin tasks are blocked from accessing:

Other users’ profiles (USER.md)
Episodic memory (consolidated summaries)
Agent journal (JOURNAL.md)
Learning notes (LEARNING.md)

This prevents cross-user information leakage.

Telemetry

Usage Ping (Optional)

telemetryEnabled: true  # Default: false

If enabled, OrcBot sends:

Agent startup event
Anonymous usage statistics (task count, skill usage)
Error reports (for debugging)

Data Sent:

OrcBot version
Platform (Linux/macOS/Windows)
Task count (aggregated)

NOT Sent:

API keys
User messages
Memory content
Personal information

Opt-Out

telemetryEnabled: false

Or set environment variable:

export ORCBOT_TELEMETRY=false

Production Security Checklist

Enable Safe Mode Initially

safeMode: true

Test all features before enabling sudo mode.

Configure Admin Users

adminUsers:
  telegram: ["your-user-id"]

Only trusted users should have admin access.

Set Command Deny List

commandDenyList:
  - rm -rf
  - dd
  - format

Block destructive commands.

Restrict Plugin Loading

pluginAllowList:
  - approved-plugin-1
  - approved-plugin-2

Only load vetted plugins.

Secure API Keys

Use environment variables
Set file permissions: chmod 600 orcbot.config.yaml
Never commit keys to git

Enable Gateway Authentication

gatewayApiKey: strong-random-key

Require API key for all gateway requests.

Use HTTPS

Set up nginx or Caddy with Let’s Encrypt.Or use Tailscale for private network access.

Monitor Logs

tail -f ~/.orcbot/logs/agent.log

Watch for suspicious activity.

Regular Updates

npm update
npm run build
orcbot daemon restart

Keep dependencies up to date.

Backup Configuration

cp ~/.orcbot/orcbot.config.yaml ~/backups/

Regularly backup config and memory.

Best Practices

Do’s

Run in safe mode initially
Use environment variables for secrets
Configure admin users explicitly
Set command/plugin allow lists in production
Use Tailscale or VPN for remote access
Monitor logs for suspicious activity
Regularly update dependencies
Backup configuration and memory

Don’ts

Don’t run as root/administrator
Don’t commit API keys to git
Don’t expose web gateway publicly without auth
Don’t disable all guardrails in multi-user environments
Don’t share admin credentials
Don’t trust unvetted plugins
Don’t ignore security warnings in logs

Configuration Reference

Complete list of security-related config options

Security Settings API

API reference for security configuration

Admin Skills

Skills that require admin permissions

Web Gateway

Setup guide for the web gateway

Get Started

Core Concepts

Guides

Advanced

​Overview

​Security Modes

​Safe Mode

​Sudo Mode (Default)

​Override Mode

​Command Security

​Allow/Deny Lists

​Platform-Specific Commands

​Plugin Security

​Allow/Deny Lists

​Plugin Health Monitoring

​Manual Plugin Management

​Admin Permissions

​Configuring Admins

​Admin-Only Skills

​Temporary Elevation

​Configuration Policy

​Policy Levels

​Approving Config Changes

​API Key Management

​Secure Storage

​Key Rotation

​Web Gateway Security

​API Key Authentication

​CORS Configuration

​HTTPS via Reverse Proxy

​Tailscale Private Network

​Data Privacy

​Local-First Architecture

​Session Isolation

​Information Boundaries

​Telemetry

​Usage Ping (Optional)

​Opt-Out

​Production Security Checklist

​Best Practices

​Do’s

​Don’ts

​Related Configuration

Configuration Reference

Security Settings API

Admin Skills

Web Gateway

Overview

Security Modes

Safe Mode

Sudo Mode (Default)

Override Mode

Command Security

Allow/Deny Lists

Platform-Specific Commands

Plugin Security

Allow/Deny Lists

Plugin Health Monitoring

Manual Plugin Management

Admin Permissions

Configuring Admins

Admin-Only Skills

Temporary Elevation

Configuration Policy

Policy Levels

Approving Config Changes

API Key Management

Secure Storage

Key Rotation

Web Gateway Security

API Key Authentication

CORS Configuration

HTTPS via Reverse Proxy

Tailscale Private Network

Data Privacy

Local-First Architecture

Session Isolation

Information Boundaries

Telemetry

Usage Ping (Optional)

Opt-Out

Production Security Checklist

Best Practices

Do’s

Don’ts

Related Configuration