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

# Quick Start

> Get OrcBot running in 5 minutes with this step-by-step guide

## Prerequisites

Before you begin, ensure you have:

* **Node.js 18+** installed
* An **OpenAI API key** or other supported LLM provider
* Terminal access (Linux, macOS, or Windows with PowerShell)

<Warning>
  OrcBot requires API keys for LLM providers. Have your OpenAI, Google Gemini, or other API key ready.
</Warning>

## Installation

<Steps>
  <Step title="Install with one command">
    Choose your platform:

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

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

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

        # Copy and edit environment variables
        cp .env.example .env

        # Start with Docker Compose
        docker compose -f docker-compose.minimal.yml up -d
        ```
      </Tab>

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

        # Install dependencies
        npm install

        # Build the project
        npm run build

        # Run setup wizard
        npm run setup
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Run the setup wizard">
    Launch the interactive configuration:

    ```bash theme={null}
    orcbot setup
    ```

    The wizard will guide you through:

    * Setting your AI model (OpenAI, Google Gemini, etc.)
    * Configuring API keys
    * Setting up communication channels (optional)
    * Choosing autonomy settings

    <Tip>
      For a minimal setup, you only need an OpenAI API key. Other channels can be configured later.
    </Tip>
  </Step>

  <Step title="Start OrcBot">
    Launch the agent loop:

    ```bash theme={null}
    orcbot run
    ```

    <CodeGroup>
      ```bash Foreground Mode theme={null}
      # Run in the current terminal (Ctrl+C to stop)
      orcbot run
      ```

      ```bash Daemon Mode theme={null}
      # Run as background service
      orcbot run --daemon

      # Check status
      orcbot daemon status

      # Stop daemon
      orcbot daemon stop
      ```

      ```bash With Web Gateway theme={null}
      # Start agent loop + REST API server
      orcbot run --with-gateway

      # Dashboard available at http://localhost:3100
      ```
    </CodeGroup>

    <Info>
      OrcBot includes conflict detection. Only one instance can run at a time to prevent duplicate operations.
    </Info>
  </Step>
</Steps>

## Your First Task

<Steps>
  <Step title="Push a manual task">
    While OrcBot is running, open a new terminal and push a task:

    ```bash theme={null}
    orcbot push "Search for the latest AI news and summarize the top 3 stories"
    ```

    You can also specify priority (1-10, default 5):

    ```bash theme={null}
    orcbot push "Deploy the staging branch" --priority 8
    ```
  </Step>

  <Step title="Watch the reasoning process">
    OrcBot will:

    1. **SIMULATE**: Create a pre-execution plan
    2. **THINK**: Reason about the task
    3. **ACT**: Execute skills (web\_search, browser\_navigate, etc.)
    4. **OBSERVE**: Process results
    5. **FINALIZE**: Complete the task

    Example output:

    ```
    [SIMULATE] Planning task: Search for latest AI news...
    [THOUGHT] I need to search the web for recent AI news articles
    [ACTION] web_search("latest AI news 2024")
    [OBSERVATION] Found 10 results from various sources...
    [THOUGHT] I should extract the top 3 articles and summarize them
    [ACTION] browser_navigate("https://example.com/ai-article")
    [OBSERVATION] Retrieved article content...
    [FINALIZE] Task completed successfully
    ```
  </Step>

  <Step title="Check the results">
    View recent memory and task status:

    ```bash theme={null}
    orcbot status
    ```

    This shows:

    * Running instance status
    * Action queue state
    * Memory statistics
    * Recent activities
  </Step>
</Steps>

## Interactive TUI Dashboard

For a visual interface, launch the TUI (Terminal User Interface):

```bash theme={null}
orcbot ui
```

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/fredabila-orcbot-61/images/tui-dashboard.png" alt="OrcBot TUI Dashboard" />
</Frame>

The TUI provides:

* **Real-time Dashboard**: Agent status, queue, memory stats
* **Model Management**: Configure OpenAI, Gemini, and other providers
* **Connection Setup**: Telegram, WhatsApp, Discord, Slack
* **Skill Management**: Install, activate, and configure skills
* **Worker Management**: Monitor multi-agent orchestration
* **Token Usage**: View API consumption and costs
* **Security Settings**: Configure admin permissions and safe mode

## Common Commands

<CodeGroup>
  ```bash Start Agent theme={null}
  # Foreground
  orcbot run

  # Background daemon
  orcbot run --daemon

  # With web gateway
  orcbot run --with-gateway
  ```

  ```bash Manage Tasks theme={null}
  # Push a task
  orcbot push "Your task here" --priority 5

  # View status
  orcbot status

  # Open TUI
  orcbot ui
  ```

  ```bash Configuration theme={null}
  # Run setup wizard
  orcbot setup

  # Get config value
  orcbot config get modelName

  # Set config value
  orcbot config set modelName gpt-4o
  ```

  ```bash Skills & Tools theme={null}
  # List installed skills
  orcbot skill list

  # Install a skill
  orcbot skill install <github-url>

  # Create new skill
  orcbot skill create my-skill
  ```

  ```bash System Control theme={null}
  # Stop all instances
  orcbot stop

  # Check daemon status
  orcbot daemon status

  # Update OrcBot
  orcbot update
  ```
</CodeGroup>

## Example Workflows

### Daily News Briefing

```bash theme={null}
orcbot push "Search for tech news from the last 24 hours, \
summarize the top 5 stories, and save to my journal" --priority 5
```

### System Monitoring

```bash theme={null}
orcbot push "Check disk usage, CPU load, and memory. \
If any metric exceeds 80%, send me an alert" --priority 8
```

### Code Review Helper

```bash theme={null}
orcbot push "Read the latest commit in the main branch, \
analyze the changes, and write a summary with potential issues" --priority 6
```

### Research Assistant

```bash theme={null}
orcbot push "Research quantum computing breakthroughs in 2024, \
ingest the findings into my knowledge base, and create a summary report" --priority 4
```

## Web Gateway (Optional)

The web gateway provides REST API and WebSocket access:

<Steps>
  <Step title="Start the gateway">
    ```bash theme={null}
    orcbot gateway --port 3100 --api-key your-secret-key
    ```

    Or start with the agent loop:

    ```bash theme={null}
    orcbot run --with-gateway
    ```
  </Step>

  <Step title="Test the API">
    ```bash theme={null}
    # Check agent status
    curl -H "X-Api-Key: your-secret-key" \
      http://localhost:3100/api/status

    # Push a task
    curl -X POST \
      -H "X-Api-Key: your-secret-key" \
      -H "Content-Type: application/json" \
      -d '{"task": "Hello from API", "priority": 5}' \
      http://localhost:3100/api/tasks
    ```
  </Step>

  <Step title="Connect via WebSocket">
    ```javascript theme={null}
    const ws = new WebSocket('ws://localhost:3100');

    ws.on('open', () => {
      ws.send(JSON.stringify({
        action: 'pushTask',
        data: { task: 'Test task', priority: 5 }
      }));
    });

    ws.on('message', (data) => {
      const event = JSON.parse(data);
      console.log('Event:', event.type, event.data);
    });
    ```
  </Step>
</Steps>

<Warning>
  For remote access, use Tailscale or another VPN instead of exposing the gateway port publicly. Always set an API key.
</Warning>

## Setting Up Communication Channels

<Tabs>
  <Tab title="Telegram">
    1. Create a bot with [@BotFather](https://t.me/botfather)
    2. Get your bot token
    3. Configure OrcBot:
       ```bash theme={null}
       orcbot config set telegramToken "your-bot-token"
       ```
    4. Restart OrcBot
    5. Start a chat with your bot on Telegram
  </Tab>

  <Tab title="Discord">
    1. Create a Discord application at [Discord Developer Portal](https://discord.com/developers/applications)
    2. Create a bot and get the token
    3. Configure OrcBot:
       ```bash theme={null}
       orcbot config set discordToken "your-bot-token"
       ```
    4. Invite the bot to your server
    5. Restart OrcBot
  </Tab>

  <Tab title="WhatsApp">
    1. Enable WhatsApp:
       ```bash theme={null}
       orcbot config set whatsappEnabled true
       ```
    2. Start OrcBot - a QR code will appear
    3. Scan the QR code with WhatsApp (Settings > Linked Devices)
    4. Session is saved for future runs
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation Guide" icon="download" href="/installation">
    Detailed setup instructions for all platforms
  </Card>

  <Card title="Configuration" icon="sliders" href="/guides/configuration">
    Learn about all configuration options
  </Card>

  <Card title="Skills System" icon="puzzle-piece" href="/concepts/skills-system">
    Extend OrcBot with custom skills
  </Card>

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="OrcBot won't start">
    Check for existing instances:

    ```bash theme={null}
    orcbot status
    ```

    If a stale instance is detected:

    ```bash theme={null}
    orcbot stop
    ```

    Then try starting again:

    ```bash theme={null}
    orcbot run
    ```
  </Accordion>

  <Accordion title="API key errors">
    Verify your API key is set:

    ```bash theme={null}
    orcbot config get openaiApiKey
    ```

    Set it if missing:

    ```bash theme={null}
    orcbot config set openaiApiKey "sk-..."
    ```

    Or use environment variables:

    ```bash theme={null}
    export OPENAI_API_KEY="sk-..."
    ```
  </Accordion>

  <Accordion title="Port conflicts">
    If the gateway port is in use:

    ```bash theme={null}
    orcbot gateway --port 3200
    ```

    Or set it in config:

    ```bash theme={null}
    orcbot config set gatewayPort 3200
    ```
  </Accordion>

  <Accordion title="Memory issues">
    Reset memory if corrupted:

    ```bash theme={null}
    orcbot reset --memory
    ```

    View memory stats:

    ```bash theme={null}
    orcbot status
    ```
  </Accordion>
</AccordionGroup>

## Getting Help

* **GitHub Issues**: [Report bugs or request features](https://github.com/fredabila/orcbot/issues)
* **Documentation**: [Full documentation](https://fredabila.github.io/orcbot/docs/)
* **Discord Community**: Join the OrcBot Discord server

<Tip>
  Run `orcbot --help` or `orcbot <command> --help` for detailed command information.
</Tip>