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

# Installation

> Complete installation guide for OrcBot on all platforms with detailed setup instructions

## System Requirements

<Note>
  OrcBot is a Node.js application that runs on Linux, macOS, and Windows.
</Note>

### Minimum Requirements

* **Node.js**: 18.x or higher
* **npm**: 8.x or higher
* **RAM**: 512 MB minimum, 2 GB recommended
* **Disk**: 500 MB for installation, 2+ GB for operation
* **Network**: Internet connection for LLM API calls

### Recommended Setup

* **Node.js**: Latest LTS version (20.x)
* **RAM**: 4 GB or more for browser automation
* **Disk**: SSD with 5+ GB free space
* **OS**: Linux (Ubuntu 22.04+), macOS (12+), or Windows 10+

## One-Line Installation

The fastest way to install OrcBot:

<Tabs>
  <Tab title="Linux / macOS">
    ```bash theme={null}
    curl -sSL https://orcbot.ai/install.sh | bash
    ```

    The installer will:

    * Check for Node.js and npm
    * Clone the repository
    * Install dependencies
    * Build the project
    * Add `orcbot` to your PATH
    * Run the setup wizard

    <Info>
      If you prefer to review the script first: `curl -sSL https://orcbot.ai/install.sh > install.sh && bash install.sh`
    </Info>
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    iwr https://orcbot.vercel.app/install.ps1 | iex
    ```

    The installer will:

    * Verify Node.js installation
    * Download the repository
    * Install dependencies
    * Compile TypeScript
    * Configure system PATH
    * Launch setup wizard

    <Warning>
      Run PowerShell as Administrator for proper PATH configuration.
    </Warning>
  </Tab>
</Tabs>

## Manual Installation

<Steps>
  <Step title="Install Node.js">
    Download and install Node.js 18+ from [nodejs.org](https://nodejs.org/).

    Verify installation:

    ```bash theme={null}
    node --version  # Should be v18.0.0 or higher
    npm --version   # Should be 8.0.0 or higher
    ```

    <Tabs>
      <Tab title="Ubuntu / Debian">
        ```bash theme={null}
        # Using NodeSource repository
        curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
        sudo apt-get install -y nodejs
        ```
      </Tab>

      <Tab title="macOS">
        ```bash theme={null}
        # Using Homebrew
        brew install node@20
        ```
      </Tab>

      <Tab title="Windows">
        Download the installer from [nodejs.org](https://nodejs.org/) and run it.
        Or use Chocolatey:

        ```powershell theme={null}
        choco install nodejs-lts
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/fredabila/orcbot.git
    cd orcbot
    ```

    <Tip>
      For a specific version: `git clone --branch v2.1.0 https://github.com/fredabila/orcbot.git`
    </Tip>
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    npm install
    ```

    This installs all required packages including:

    * TypeScript compiler
    * Playwright for browser automation
    * Telegraf for Telegram integration
    * Discord.js for Discord support
    * WhatsApp Baileys for WhatsApp
    * And more...

    <Note>
      Installation may take 3-5 minutes depending on your network speed.
    </Note>
  </Step>

  <Step title="Build the Project">
    Compile TypeScript to JavaScript:

    ```bash theme={null}
    npm run build
    ```

    Or use the fast build (using esbuild):

    ```bash theme={null}
    npm run build:fast
    ```

    The compiled output will be in the `dist/` directory.
  </Step>

  <Step title="Run Setup Wizard">
    ```bash theme={null}
    npm run setup
    ```

    Or if the binary is built:

    ```bash theme={null}
    ./dist/cli/index.js setup
    ```

    The wizard will configure:

    * AI model and provider
    * API keys
    * Communication channels
    * Agent identity
    * Autonomy settings
  </Step>

  <Step title="Make CLI Globally Available (Optional)">
    <Tabs>
      <Tab title="npm link">
        ```bash theme={null}
        npm link
        ```

        Now you can run `orcbot` from anywhere.
      </Tab>

      <Tab title="Add to PATH">
        Add the `dist/cli` directory to your PATH:

        ```bash theme={null}
        echo 'export PATH="$PATH:/path/to/orcbot/dist/cli"' >> ~/.bashrc
        source ~/.bashrc
        ```
      </Tab>

      <Tab title="Alias">
        Create an alias in your shell config:

        ```bash theme={null}
        echo 'alias orcbot="node /path/to/orcbot/dist/cli/index.js"' >> ~/.bashrc
        source ~/.bashrc
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Docker Installation

<Warning>
  Docker deployment is recommended for production servers and consistent environments.
</Warning>

<Steps>
  <Step title="Install Docker">
    Install Docker and Docker Compose:

    <Tabs>
      <Tab title="Linux">
        ```bash theme={null}
        # Docker
        curl -fsSL https://get.docker.com | sh

        # Docker Compose
        sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" \
          -o /usr/local/bin/docker-compose
        sudo chmod +x /usr/local/bin/docker-compose
        ```
      </Tab>

      <Tab title="macOS">
        Download [Docker Desktop for Mac](https://www.docker.com/products/docker-desktop).
      </Tab>

      <Tab title="Windows">
        Download [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop).
      </Tab>
    </Tabs>
  </Step>

  <Step title="Prepare Configuration">
    Clone the repository and copy the example environment file:

    ```bash theme={null}
    git clone https://github.com/fredabila/orcbot.git
    cd orcbot
    cp .env.example .env
    ```

    Edit `.env` with your API keys and settings:

    ```bash theme={null}
    nano .env  # or use your preferred editor
    ```

    Required variables:

    ```bash theme={null}
    OPENAI_API_KEY=sk-...
    MODEL_NAME=gpt-4o
    AGENT_NAME=OrcBot
    ```
  </Step>

  <Step title="Choose a Docker Compose File">
    OrcBot provides multiple Docker configurations:

    <Tabs>
      <Tab title="Minimal">
        Basic setup with core features:

        ```bash theme={null}
        docker compose -f docker-compose.minimal.yml up -d
        ```
      </Tab>

      <Tab title="Full">
        Complete setup with all features:

        ```bash theme={null}
        docker compose -f docker-compose.yml up -d
        ```
      </Tab>

      <Tab title="Development">
        Development mode with hot reload:

        ```bash theme={null}
        docker compose -f docker-compose.dev.yml up
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Access the Dashboard">
    Once running, access the web gateway:

    ```
    http://localhost:3100
    ```

    View logs:

    ```bash theme={null}
    docker compose logs -f orcbot
    ```

    Stop the container:

    ```bash theme={null}
    docker compose down
    ```
  </Step>
</Steps>

### Docker Management

<CodeGroup>
  ```bash Start/Stop theme={null}
  # Start
  docker compose up -d

  # Stop
  docker compose down

  # Restart
  docker compose restart
  ```

  ```bash Logs theme={null}
  # View logs
  docker compose logs -f

  # Last 100 lines
  docker compose logs --tail=100
  ```

  ```bash Shell Access theme={null}
  # Enter container
  docker compose exec orcbot sh

  # Run command
  docker compose exec orcbot orcbot status
  ```

  ```bash Update theme={null}
  # Pull latest changes
  git pull

  # Rebuild and restart
  docker compose build
  docker compose up -d
  ```
</CodeGroup>

## Platform-Specific Setup

### Linux

<Tabs>
  <Tab title="Ubuntu / Debian">
    ```bash theme={null}
    # Update system
    sudo apt update && sudo apt upgrade -y

    # Install dependencies
    sudo apt install -y git curl build-essential

    # Install Node.js
    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt install -y nodejs

    # Clone and install OrcBot
    git clone https://github.com/fredabila/orcbot.git
    cd orcbot
    npm install
    npm run build
    npm run setup
    ```
  </Tab>

  <Tab title="Fedora / RHEL">
    ```bash theme={null}
    # Install Node.js
    sudo dnf install -y nodejs npm git

    # Clone and install OrcBot
    git clone https://github.com/fredabila/orcbot.git
    cd orcbot
    npm install
    npm run build
    npm run setup
    ```
  </Tab>

  <Tab title="Arch Linux">
    ```bash theme={null}
    # Install Node.js
    sudo pacman -S nodejs npm git

    # Clone and install OrcBot
    git clone https://github.com/fredabila/orcbot.git
    cd orcbot
    npm install
    npm run build
    npm run setup
    ```
  </Tab>
</Tabs>

#### Linux System Service

Create a systemd service for OrcBot:

```bash theme={null}
sudo nano /etc/systemd/system/orcbot.service
```

Add:

```ini theme={null}
[Unit]
Description=OrcBot Autonomous Agent
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/orcbot
ExecStart=/usr/bin/node /path/to/orcbot/dist/cli/index.js run --daemon
Restart=on-failure
RestartSec=10
Environment="NODE_ENV=production"
Environment="OPENAI_API_KEY=your-key-here"

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable orcbot
sudo systemctl start orcbot
sudo systemctl status orcbot
```

### macOS

```bash theme={null}
# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node@20

# Clone repository
git clone https://github.com/fredabila/orcbot.git
cd orcbot

# Install and build
npm install
npm run build
npm run setup
```

#### macOS Launch Agent

Create a launch agent to run OrcBot at login:

```bash theme={null}
nano ~/Library/LaunchAgents/com.orcbot.agent.plist
```

Add:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.orcbot.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>/path/to/orcbot/dist/cli/index.js</string>
        <string>run</string>
        <string>--daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/orcbot.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/orcbot.error.log</string>
</dict>
</plist>
```

Load the agent:

```bash theme={null}
launchctl load ~/Library/LaunchAgents/com.orcbot.agent.plist
```

### Windows

<Steps>
  <Step title="Install Prerequisites">
    Using PowerShell (as Administrator):

    ```powershell theme={null}
    # Install Chocolatey
    Set-ExecutionPolicy Bypass -Scope Process -Force
    [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
    iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

    # Install Node.js and Git
    choco install nodejs-lts git -y
    ```
  </Step>

  <Step title="Clone and Install">
    ```powershell theme={null}
    # Clone repository
    git clone https://github.com/fredabila/orcbot.git
    cd orcbot

    # Install dependencies
    npm install

    # Build
    npm run build

    # Setup
    npm run setup
    ```
  </Step>

  <Step title="Run OrcBot">
    ```powershell theme={null}
    # Start in foreground
    node dist/cli/index.js run

    # Or start in background
    Start-Process -NoNewWindow -FilePath "node" -ArgumentList "dist/cli/index.js", "run", "--daemon"
    ```
  </Step>
</Steps>

#### Windows Service

To run OrcBot as a Windows service, use [node-windows](https://github.com/coreybutler/node-windows):

```powershell theme={null}
npm install -g node-windows
```

Create `service.js`:

```javascript theme={null}
const Service = require('node-windows').Service;

const svc = new Service({
  name: 'OrcBot',
  description: 'OrcBot Autonomous Agent',
  script: 'C:\\path\\to\\orcbot\\dist\\cli\\index.js',
  scriptOptions: 'run --daemon',
  nodeOptions: ['--harmony', '--max_old_space_size=4096']
});

svc.on('install', () => {
  svc.start();
});

svc.install();
```

Install:

```powershell theme={null}
node service.js
```

## Configuration

After installation, configure OrcBot:

<Steps>
  <Step title="Run Setup Wizard">
    ```bash theme={null}
    orcbot setup
    ```

    The wizard configures:

    * **AI Model**: Choose OpenAI, Google Gemini, AWS Bedrock, etc.
    * **API Keys**: Enter your provider API keys
    * **Channels**: Configure Telegram, Discord, WhatsApp
    * **Identity**: Set agent name and personality
    * **Autonomy**: Enable/disable autonomous operations
  </Step>

  <Step title="Manual Configuration">
    Configuration files are stored in `~/.orcbot/`:

    * `orcbot.config.yaml`: Main configuration
    * `.env`: Environment variables
    * `AGENTS.md`, `SOUL.md`: Bootstrap files

    Edit the config:

    ```bash theme={null}
    nano ~/.orcbot/orcbot.config.yaml
    ```

    Key settings:

    ```yaml theme={null}
    # LLM Configuration
    modelName: gpt-4o
    llmProvider: openai
    openaiApiKey: sk-...

    # Channels
    telegramToken: "your-bot-token"
    discordToken: "your-discord-token"
    whatsappEnabled: false

    # Autonomy
    autonomyEnabled: true
    autonomyInterval: 3600

    # Web Gateway
    gatewayPort: 3100
    gatewayApiKey: "your-secret-key"
    ```
  </Step>

  <Step title="Environment Variables">
    Alternatively, use environment variables:

    ```bash theme={null}
    export OPENAI_API_KEY="sk-..."
    export MODEL_NAME="gpt-4o"
    export TELEGRAM_TOKEN="your-bot-token"
    export AGENT_NAME="OrcBot"
    ```

    <Tip>
      Environment variables override config file settings.
    </Tip>
  </Step>
</Steps>

## Verification

Verify your installation:

<Steps>
  <Step title="Check Version">
    ```bash theme={null}
    orcbot --version
    ```
  </Step>

  <Step title="Test Configuration">
    ```bash theme={null}
    orcbot config get modelName
    ```
  </Step>

  <Step title="Run Status Check">
    ```bash theme={null}
    orcbot status
    ```
  </Step>

  <Step title="Test a Simple Task">
    ```bash theme={null}
    orcbot run &
    sleep 3
    orcbot push "What is 2+2?"
    ```
  </Step>

  <Step title="Check Logs">
    ```bash theme={null}
    tail -f ~/.orcbot/daemon.log
    ```
  </Step>
</Steps>

## Optional Components

### Lightpanda Browser (Lightweight)

Lightpanda uses 9x less RAM than Chrome:

```bash theme={null}
# Install
orcbot lightpanda install

# Start
orcbot lightpanda start --background

# Enable
orcbot lightpanda enable
```

<Note>
  Lightpanda is only available on Linux x64 and macOS ARM64. Use WSL2 on Windows.
</Note>

### Ollama (Local LLMs)

Run LLMs locally without API calls:

```bash theme={null}
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama2

# Configure OrcBot
orcbot config set modelName ollama/llama2
orcbot config set llmProvider ollama
orcbot config set ollamaEndpoint http://localhost:11434
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="npm install fails">
    Clear npm cache:

    ```bash theme={null}
    npm cache clean --force
    npm install
    ```

    Or delete `node_modules` and reinstall:

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>

  <Accordion title="Build errors">
    Check TypeScript version:

    ```bash theme={null}
    npm list typescript
    ```

    Reinstall TypeScript:

    ```bash theme={null}
    npm install --save-dev typescript@latest
    npm run build
    ```
  </Accordion>

  <Accordion title="Permission errors (Linux/macOS)">
    Don't use `sudo` with npm. Fix permissions:

    ```bash theme={null}
    sudo chown -R $USER:$USER ~/.npm
    sudo chown -R $USER:$USER ~/.orcbot
    ```
  </Accordion>

  <Accordion title="PATH not updated">
    Manually add to PATH:

    ```bash theme={null}
    echo 'export PATH="$PATH:$HOME/.orcbot/bin"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Accordion>

  <Accordion title="Playwright browser installation fails">
    Install browsers manually:

    ```bash theme={null}
    npx playwright install chromium
    ```
  </Accordion>
</AccordionGroup>

## Updating OrcBot

<Tabs>
  <Tab title="Automatic">
    ```bash theme={null}
    orcbot update
    ```
  </Tab>

  <Tab title="Manual">
    ```bash theme={null}
    cd /path/to/orcbot
    git pull origin main
    npm install
    npm run build
    ```
  </Tab>

  <Tab title="Docker">
    ```bash theme={null}
    docker compose pull
    docker compose up -d
    ```
  </Tab>
</Tabs>

## Uninstallation

<Warning>
  This will remove OrcBot and all its data. Make sure to backup important configurations and memory files.
</Warning>

```bash theme={null}
# Stop OrcBot
orcbot stop

# Remove installation directory
rm -rf /path/to/orcbot

# Remove data directory
rm -rf ~/.orcbot

# Remove from PATH (if using npm link)
npm unlink orcbot
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get up and running in 5 minutes
  </Card>

  <Card title="Configuration" icon="sliders" href="/configuration">
    Configure OrcBot for your use case
  </Card>

  <Card title="Skills & Plugins" icon="puzzle-piece" href="/skills">
    Extend OrcBot with custom skills
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Complete API documentation
  </Card>
</CardGroup>