Installation Guide

This guide will walk you through the process of installing CleverBee on your system, including prerequisites, installation steps, and platform-specific considerations.

Table of Contents

Prerequisites

Before installing CleverBee, ensure your system meets the following requirements:

Note

The setup script will attempt to install some dependencies, but you should ensure your system has the core requirements (Python, git, jq, CMake if local models chosen) before proceeding.

Installing Required Packages

On macOS:

brew install python cmake git jq node

On Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip python3-venv cmake git jq nodejs

Installation Steps

Follow these steps to install CleverBee:

  1. Clone the repository: 
    git clone https://github.com/SureScaleAI/cleverbee
cd cleverbee
  2. Run the setup script: 
    bash setup.sh

    This script will guide you through:

    • Checking prerequisites (python3, jq, yq, cmake if local models chosen)
    • Creating a Python virtual environment (venv/)
    • Installing base Python dependencies from requirements.txt
    • Hardware Check & Model Preference: Asking if you want to enable local model setup (currently optimized for NVIDIA GPUs >= 24GB VRAM)
    • Conditional llama-cpp-python Install: Installing with appropriate hardware acceleration (CUDA for NVIDIA) if local models are enabled
    • Hugging Face Login: Prompting login if using local models
    • Model Configuration: Helping select primary reasoning and summarizer models, updating config.yaml
    • Model Download: Downloading selected local GGUF models if chosen
    • GPU Layer Optimization: Recommending and setting N_GPU_LAYERS in config.yaml for local models
    • Additional Config: Helping set memory limits and thinking mode in config.yaml
    • Installing necessary Playwright browsers and applying rebrowser patches
    • API Key Setup: Checking for needed API keys (ANTHROPIC_API_KEY, GEMINI_API_KEY) in .env based on selected models and prompting if missing
    • Making run.sh executable

Important

The setup process might take 15-30 minutes, especially when downloading models. GPU detection and model selection will be interactive, requiring your input during setup.

API Keys

CleverBee requires API keys for cloud models. The setup script will check if you need API keys based on your model selection and help you add them to the .env file:

If you need to add or change keys later, edit the .env file directly and restart the application.

Hardware Considerations

Important

We strongly discourage the use of local LLMs without a good NVIDIA GPU. Running research flows on systems without proper GPU acceleration can take hours or even days to complete. Cloud models like Gemini or Claude are strongly recommended for systems without NVIDIA GPUs.

RAM Requirements

GPU Acceleration

Local models can benefit significantly from GPU acceleration:

The setup script will detect your hardware and recommend appropriate settings.

Platform-Specific Instructions

macOS

Linux with NVIDIA GPUs

Windows

Model Selection

During setup, you'll be prompted to select models for two distinct purposes:

1. Primary Reasoning Model

This model handles the research planning, tool selection, and report writing. Options include:

2. Summarizer Model

This model processes and summarizes content. Options include:

The setup script will recommend appropriate models based on your hardware.

Installation Troubleshooting

Common Issues

Issue: Model Download Failures

Solution: Ensure you've logged into Hugging Face using huggingface-cli login and accepted model terms. You can re-run setup.sh to retry downloads.

Issue: Missing Dependencies

Solution: Install missing system dependencies (like CMake, jq) and re-run the setup script.

Issue: GPU Acceleration Not Working

Solution: Ensure you have proper drivers installed. Check config.yaml and verify N_GPU_LAYERS is set appropriately.

Getting Help

If you encounter issues during installation:

Next Steps

Once installation is complete, proceed to the Configuration Guide to customize CleverBee for your needs, or jump to the Usage Guide to start using it right away.