> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcbot.buzzchat.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Configuration

> Configure safeMode, admin permissions, API keys, and plugin security

## Overview

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

## Security Modes

### Safe Mode

<ParamField path="safeMode" type="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

  ```yaml theme={null}
  safeMode: true  # Production-safe setting
  ```
</ParamField>

### Sudo Mode

<ParamField path="sudoMode" type="boolean" default={false}>
  Enable unrestricted access mode (bypasses command allow/deny lists).

  **Policy:** LOCKED - Security-critical configuration.

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

  ```yaml theme={null}
  sudoMode: false  # Recommended for all deployments
  ```
</ParamField>

### Override Mode

<ParamField path="overrideMode" type="boolean" default={false}>
  Enable behavioral override mode that bypasses persona boundaries.

  **Policy:** LOCKED - Security-critical configuration.

  <Warning>
    **Experimental feature.** Override mode allows the agent to bypass its normal behavioral constraints.
  </Warning>

  ```yaml theme={null}
  overrideMode: false  # Keep disabled unless testing
  ```
</ParamField>

## Command Security

### Command Allow List

<ParamField path="commandAllowList" type="array">
  Whitelist of allowed shell commands. Empty list means all commands are blocked (unless in sudo mode).

  Default includes common development tools:

  ```yaml theme={null}
  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
  ```
</ParamField>

### Command Deny List

<ParamField path="commandDenyList" type="array">
  Blacklist of denied commands. Takes precedence over allow list.

  **Policy:** LOCKED - Security-critical configuration.

  Default blocks destructive operations:

  ```yaml theme={null}
  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
  ```

  <Note>
    The deny list is enforced even in sudo mode to prevent accidental catastrophic operations.
  </Note>
</ParamField>

### Command Execution Settings

<ParamField path="commandTimeoutMs" type="number" default={120000}>
  Timeout for shell command execution in milliseconds (default: 2 minutes).

  Prevents runaway processes from consuming resources indefinitely.
</ParamField>

<ParamField path="commandRetries" type="number" default={1}>
  Number of retries for failed commands.
</ParamField>

<ParamField path="commandWorkingDir" type="string">
  Working directory for command execution. Defaults to current directory.
</ParamField>

<ParamField path="autoExecuteCommands" type="boolean" default={false}>
  Automatically execute commands without confirmation.

  <Warning>
    **Disable for production.** Auto-execution bypasses human oversight.
  </Warning>
</ParamField>

### Example: Lockdown Configuration

```yaml orcbot.config.yaml theme={null}
# 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

<ParamField path="pluginAllowList" type="array" default={[]}>
  Whitelist of allowed plugins. Empty array means all plugins are allowed.

  ```yaml theme={null}
  pluginAllowList:
    - stripe-payment
    - calendar-sync
    - custom-search
  ```

  <Note>
    When `pluginAllowList` is non-empty, only plugins in the list can be loaded.
  </Note>
</ParamField>

### Plugin Deny List

<ParamField path="pluginDenyList" type="array" default={[]}>
  Blacklist of denied plugins. Takes precedence over allow list.

  ```yaml theme={null}
  pluginDenyList:
    - experimental-plugin
    - untrusted-plugin
  ```
</ParamField>

### Plugin Health Monitoring

<ParamField path="pluginHealthCheckIntervalMinutes" type="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.
</ParamField>

### Example: Plugin Security

```yaml orcbot.config.yaml theme={null}
# Strict plugin control
pluginAllowList:
  - approved-plugin-1
  - approved-plugin-2

pluginDenyList:
  - dangerous-plugin
  - untested-plugin

# Frequent health checks
pluginHealthCheckIntervalMinutes: 10
```

## Admin Permissions

<ParamField path="adminUsers" type="object">
  Per-channel admin user allowlists. Admins have access to elevated commands and skills.

  **Policy:** LOCKED - Security-critical configuration.

  ```yaml theme={null}
  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
  ```
</ParamField>

### Admin-Only Skills

These skills are restricted to admin users:

<CardGroup cols={2}>
  <Card title="run_command" icon="terminal">
    Execute shell commands on the host system.
  </Card>

  <Card title="create_custom_skill" icon="code">
    Create executable TypeScript plugin skills.
  </Card>

  <Card title="manage_config" icon="gear">
    Modify configuration settings (subject to policy).
  </Card>

  <Card title="spawn_agent" icon="users">
    Create worker agent processes.
  </Card>

  <Card title="delegate_task" icon="share-nodes">
    Orchestrate tasks across multiple agents.
  </Card>

  <Card title="system_check" icon="circle-check">
    Verify system dependencies and commands.
  </Card>

  <Card title="self_repair_skill" icon="wrench">
    Repair broken plugin code.
  </Card>

  <Card title="execute_typescript" icon="file-code">
    Write and execute TypeScript scripts.
  </Card>
</CardGroup>

<Warning>
  **Non-admin users cannot execute admin-only skills.** Attempts will be logged and blocked.
</Warning>

## Configuration Policy

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

### Policy Levels

<AccordionGroup>
  <Accordion title="SAFE - Agent can modify" icon="check">
    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:**

    ```yaml theme={null}
    # Agent can adjust these freely
    modelName: gpt-4o          # SAFE
    memoryContextLimit: 30     # SAFE
    maxStepsPerAction: 40      # SAFE
    ```
  </Accordion>

  <Accordion title="APPROVAL - Requires approval" icon="user-check">
    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:**

    ```yaml theme={null}
    # Agent can request changes, human approves
    openaiApiKey: sk-...       # APPROVAL
    autonomyEnabled: true      # APPROVAL
    ```

    <Note>
      Agents can view pending approvals with `manage_config({ action: "pending" })`
    </Note>
  </Accordion>

  <Accordion title="LOCKED - Agent cannot modify" icon="lock">
    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:**

    ```yaml theme={null}
    # Agent cannot modify these at all
    safeMode: true             # LOCKED
    telegramToken: "..."       # LOCKED
    adminUsers:                # LOCKED
      telegram: ["123456"]
    ```

    <Warning>
      Attempts to modify LOCKED config will be rejected with an error message.
    </Warning>
  </Accordion>
</AccordionGroup>

### Policy Usage

Agents use the `manage_config` skill to interact with configuration:

```yaml theme={null}
# 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

<Warning>
  **Never commit API keys to version control.** Use environment variables or local config files that are .gitignored.
</Warning>

<Steps>
  <Step title="Use environment variables">
    Store API keys in `.env` files:

    ```bash .env theme={null}
    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
    ```
  </Step>

  <Step title="Restrict file permissions">
    ```bash theme={null}
    chmod 600 .env
    chmod 700 ~/.orcbot
    ```
  </Step>

  <Step title="Use key rotation">
    Regularly rotate API keys and update configuration:

    ```bash theme={null}
    # Generate new key, then update
    orcbot config set openaiApiKey sk-new-key
    ```
  </Step>

  <Step title="Monitor usage">
    Enable token tracking to detect anomalies:

    ```yaml theme={null}
    tokenUsagePath: ~/.orcbot/token-usage-summary.json
    tokenLogPath: ~/.orcbot/token-usage.log
    ```
  </Step>
</Steps>

### API Key Configuration

All API keys support environment variable fallback:

<ParamField path="openaiApiKey" type="string">
  **Policy:** APPROVAL

  **Environment variable:** `OPENAI_API_KEY`
</ParamField>

<ParamField path="googleApiKey" type="string">
  **Policy:** APPROVAL

  **Environment variable:** `GOOGLE_API_KEY`
</ParamField>

<ParamField path="anthropicApiKey" type="string">
  **Policy:** APPROVAL

  **Environment variable:** `ANTHROPIC_API_KEY`
</ParamField>

<ParamField path="openrouterApiKey" type="string">
  **Policy:** APPROVAL

  **Environment variable:** `OPENROUTER_API_KEY`
</ParamField>

<ParamField path="nvidiaApiKey" type="string">
  **Policy:** APPROVAL

  **Environment variable:** `NVIDIA_API_KEY`
</ParamField>

<ParamField path="serperApiKey" type="string">
  **Policy:** APPROVAL

  **Environment variable:** `SERPER_API_KEY`
</ParamField>

<ParamField path="braveSearchApiKey" type="string">
  **Policy:** APPROVAL

  **Environment variable:** `BRAVE_SEARCH_API_KEY`
</ParamField>

<ParamField path="captchaApiKey" type="string">
  2Captcha API key for solving CAPTCHAs.

  **Environment variable:** `CAPTCHA_API_KEY`
</ParamField>

<ParamField path="telegramToken" type="string">
  **Policy:** LOCKED

  **Environment variable:** `TELEGRAM_TOKEN`
</ParamField>

<ParamField path="discordToken" type="string">
  **Policy:** LOCKED

  **Environment variable:** `DISCORD_TOKEN`
</ParamField>

<ParamField path="slackBotToken" type="string">
  **Policy:** LOCKED

  **Environment variable:** `SLACK_BOT_TOKEN`
</ParamField>

<ParamField path="bedrockAccessKeyId" type="string">
  **Policy:** LOCKED

  **Environment variable:** `BEDROCK_ACCESS_KEY_ID` or `AWS_ACCESS_KEY_ID`
</ParamField>

<ParamField path="bedrockSecretAccessKey" type="string">
  **Policy:** LOCKED

  **Environment variable:** `BEDROCK_SECRET_ACCESS_KEY` or `AWS_SECRET_ACCESS_KEY`
</ParamField>

## Web Gateway Security

<ParamField path="gatewayApiKey" type="string">
  API key for authenticating gateway requests.

  Required for all API endpoints when configured:

  ```bash theme={null}
  curl -H "X-Api-Key: your-key" http://localhost:3100/api/status
  ```

  <Warning>
    **Always set an API key for production deployments.** Without it, anyone can access your agent's API.
  </Warning>
</ParamField>

<ParamField path="gatewayCorsOrigins" type="array" default={["*"]}>
  CORS allowed origins for gateway API.

  ```yaml theme={null}
  gatewayCorsOrigins:
    - https://yourdomain.com
    - https://app.yourdomain.com
  ```
</ParamField>

<ParamField path="gatewayPort" type="number" default={3100}>
  HTTP port for the web gateway.
</ParamField>

<ParamField path="gatewayHost" type="string" default="0.0.0.0">
  Host address to bind the gateway server.

  <Note>
    Use `127.0.0.1` to restrict to localhost only.
  </Note>
</ParamField>

### Tailscale (Recommended)

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

<Steps>
  <Step title="Install Tailscale">
    ```bash theme={null}
    curl -fsSL https://tailscale.com/install.sh | sh
    ```
  </Step>

  <Step title="Connect to Tailnet">
    ```bash theme={null}
    sudo tailscale up
    ```
  </Step>

  <Step title="Configure gateway for Tailnet">
    ```yaml theme={null}
    gatewayHost: 0.0.0.0  # Bind to all interfaces
    gatewayPort: 3100
    gatewayApiKey: your-secret-key  # Still use API key for defense-in-depth
    ```
  </Step>

  <Step title="Set Tailnet ACLs">
    Restrict access to specific devices/users in your Tailnet.
  </Step>
</Steps>

<Note>
  Tailscale provides a private mesh network so you don't need to expose port 3100 publicly or use a reverse proxy.
</Note>

## 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`

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

### Session Isolation

<ParamField path="sessionScope" type="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)

  ```yaml theme={null}
  sessionScope: per-channel-peer  # Most private
  ```
</ParamField>

### 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

<ParamField path="usagePingEnabled" type="boolean" default={true}>
  Enable anonymous usage telemetry.

  Telemetry includes:

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

  <Note>
    No user data, messages, or API keys are included in telemetry.
  </Note>
</ParamField>

<ParamField path="usagePingUrl" type="string" default="">
  Telemetry endpoint URL (default: OrcBot telemetry service).
</ParamField>

<ParamField path="usagePingTimeoutMs" type="number" default={4000}>
  Timeout for telemetry requests in milliseconds.
</ParamField>

<ParamField path="usagePingToken" type="string" default="">
  Authentication token for telemetry (if required by endpoint).
</ParamField>

### Disable Telemetry

```yaml orcbot.config.yaml theme={null}
usagePingEnabled: false
```

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Enable Safe Mode" icon="shield">
    Use `safeMode: true` in production to prevent command execution.
  </Card>

  <Card title="Restrict Commands" icon="list-check">
    Carefully curate `commandAllowList` and `commandDenyList`.
  </Card>

  <Card title="Set Admin Users" icon="user-shield">
    Explicitly configure `adminUsers` per channel.
  </Card>

  <Card title="Secure API Keys" icon="key">
    Use environment variables and restrict file permissions.
  </Card>

  <Card title="Use Tailscale" icon="network-wired">
    Access gateway via private mesh network instead of public internet.
  </Card>

  <Card title="Set Gateway API Key" icon="lock-keyhole">
    Always configure `gatewayApiKey` for production.
  </Card>

  <Card title="Control Plugins" icon="puzzle-piece">
    Use `pluginAllowList` and `pluginDenyList` to restrict plugins.
  </Card>

  <Card title="Isolate Sessions" icon="users-rectangle">
    Use `sessionScope: per-channel-peer` for privacy.
  </Card>
</CardGroup>

## Production Security Template

```yaml orcbot.config.yaml theme={null}
# 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
```

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