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

> Security features, safe mode, admin permissions, and best practices for production deployment

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

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

## Security Modes

### Safe Mode

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

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

```yaml theme={null}
safeMode: false
autopilotNoQuestions: true
disableTerminationReview: true
```

**Minimal guardrails** for maximum autonomy.

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

## Command Security

### Allow/Deny Lists

```yaml theme={null}
# orcbot.config.yaml
commandAllowList:
  - npm
  - git
  - docker
  - ls
  - cat
  - grep

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

**How It Works:**

<Steps>
  <Step title="Command Requested">
    Agent attempts `run_command("rm -rf /tmp/file")`
  </Step>

  <Step title="Parse Command">
    Extract base command: `rm`
  </Step>

  <Step title="Check Allow List">
    If `commandAllowList` is set and `rm` is not in it, **reject**.
  </Step>

  <Step title="Check Deny List">
    If `rm -rf` matches any pattern in `commandDenyList`, **reject**.
  </Step>

  <Step title="Execute or Block">
    If all checks pass, execute. Otherwise, return error.
  </Step>
</Steps>

### Platform-Specific Commands

```yaml theme={null}
# Windows
commandDenyList:
  - del /F
  - rmdir /S
  - format

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

## Plugin Security

### Allow/Deny Lists

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

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

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

```yaml theme={null}
# orcbot.config.yaml
adminUsers:
  telegram:
    - "123456789"          # Telegram user ID
    - "@username"          # Telegram username
  discord:
    - "987654321098765432" # Discord user ID
  whatsapp:
    - "1234567890@s.whatsapp.net"
```

<Tip>
  **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.
</Tip>

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

```json theme={null}
// Non-admin user requests:
{
  "skillName": "run_command",
  "command": "ls -la"
}

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

### Temporary Elevation

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

<Tabs>
  <Tab title="SAFE">
    **Agent can modify autonomously.**

    Examples:

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

    No approval required.
  </Tab>

  <Tab title="APPROVAL">
    **Agent can request changes, human must approve.**

    Examples:

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

    Changes queue for approval.
  </Tab>

  <Tab title="LOCKED">
    **Agent cannot modify under any circumstances.**

    Examples:

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

    Only editable via config file or TUI.
  </Tab>
</Tabs>

### Approving Config Changes

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

<Steps>
  <Step title="Use Environment Variables">
    ```bash theme={null}
    export OPENAI_API_KEY="sk-..."
    export TELEGRAM_TOKEN="123..."
    ```

    OrcBot reads from environment first, then config file.
  </Step>

  <Step title="Restrict File Permissions">
    ```bash theme={null}
    chmod 600 ~/.orcbot/orcbot.config.yaml
    ```

    Only the owner can read the config file.
  </Step>

  <Step title="Use Secrets Manager (Production)">
    For cloud deployments, use AWS Secrets Manager, HashiCorp Vault, or similar.

    Load secrets at runtime:

    ```typescript theme={null}
    // Custom loader
    const secrets = await loadFromVault();
    config.openaiApiKey = secrets.OPENAI_API_KEY;
    ```
  </Step>
</Steps>

### Key Rotation

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

<Warning>
  Never commit API keys to version control. Use `.gitignore` for `orcbot.config.yaml`.
</Warning>

## Web Gateway Security

### API Key Authentication

```yaml theme={null}
# orcbot.config.yaml
gatewayApiKey: your-secret-key-here
```

Clients must include the key in requests:

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

### CORS Configuration

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

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

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

  <Step title="Configure Gateway">
    ```yaml theme={null}
    gatewayHost: 0.0.0.0  # Listen on all interfaces
    gatewayPort: 3100
    ```
  </Step>

  <Step title="Access via Tailscale IP">
    ```bash theme={null}
    curl http://100.x.y.z:3100/api/status
    ```

    Only Tailnet members can reach the gateway.
  </Step>
</Steps>

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

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

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

```yaml theme={null}
telemetryEnabled: false
```

Or set environment variable:

```bash theme={null}
export ORCBOT_TELEMETRY=false
```

## Production Security Checklist

<Steps>
  <Step title="Enable Safe Mode Initially">
    ```yaml theme={null}
    safeMode: true
    ```

    Test all features before enabling sudo mode.
  </Step>

  <Step title="Configure Admin Users">
    ```yaml theme={null}
    adminUsers:
      telegram: ["your-user-id"]
    ```

    Only trusted users should have admin access.
  </Step>

  <Step title="Set Command Deny List">
    ```yaml theme={null}
    commandDenyList:
      - rm -rf
      - dd
      - format
    ```

    Block destructive commands.
  </Step>

  <Step title="Restrict Plugin Loading">
    ```yaml theme={null}
    pluginAllowList:
      - approved-plugin-1
      - approved-plugin-2
    ```

    Only load vetted plugins.
  </Step>

  <Step title="Secure API Keys">
    * Use environment variables
    * Set file permissions: `chmod 600 orcbot.config.yaml`
    * Never commit keys to git
  </Step>

  <Step title="Enable Gateway Authentication">
    ```yaml theme={null}
    gatewayApiKey: strong-random-key
    ```

    Require API key for all gateway requests.
  </Step>

  <Step title="Use HTTPS">
    Set up nginx or Caddy with Let's Encrypt.

    Or use Tailscale for private network access.
  </Step>

  <Step title="Monitor Logs">
    ```bash theme={null}
    tail -f ~/.orcbot/logs/agent.log
    ```

    Watch for suspicious activity.
  </Step>

  <Step title="Regular Updates">
    ```bash theme={null}
    npm update
    npm run build
    orcbot daemon restart
    ```

    Keep dependencies up to date.
  </Step>

  <Step title="Backup Configuration">
    ```bash theme={null}
    cp ~/.orcbot/orcbot.config.yaml ~/backups/
    ```

    Regularly backup config and memory.
  </Step>
</Steps>

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

## Related Configuration

<CardGroup cols={2}>
  <Card title="Configuration Reference" href="/api/config/reference">
    Complete list of security-related config options
  </Card>

  <Card title="Security Settings API" href="/api/config/security">
    API reference for security configuration
  </Card>

  <Card title="Admin Skills" href="/api/skills/overview">
    Skills that require admin permissions
  </Card>

  <Card title="Web Gateway" href="/guides/web-gateway">
    Setup guide for the web gateway
  </Card>
</CardGroup>