debai/docs/INSTALLATION.md

Installation Guide

This guide provides detailed instructions for installing Debai on your GNU/Linux system.

Prerequisites

System Requirements

• Operating System: Debian 13 (Trixie) or newer, Ubuntu 24.04 or newer, or compatible
• Python: 3.10 or later
• RAM: 4GB minimum, 8GB recommended
• Disk: 10GB free space (more for AI models)
• Architecture: x86_64 (amd64)

Dependencies

Required

sudo apt update
sudo apt install -y \
    python3 \
    python3-pip \
    python3-venv \
    python3-gi \
    gir1.2-gtk-4.0 \
    gir1.2-adw-1

Recommended

sudo apt install -y \
    docker.io \
    qemu-utils \
    genisoimage

Installation Methods

Method 1: Debian Package (Recommended)

Download and install the .deb package:

# Download the latest release
wget https://github.com/manalejandro/debai/releases/latest/download/debai_1.0.0-1_all.deb

# Install
sudo dpkg -i debai_1.0.0-1_all.deb

# Install missing dependencies
sudo apt-get install -f

Method 2: From PyPI

# Install from PyPI
pip install debai

# Or with GUI support
pip install debai[gui]

Method 3: From Source

# Clone the repository
git clone https://github.com/debai/debai.git
cd debai

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

# Or with all extras
pip install -e ".[gui,dev,docs]"

Method 4: Build Debian Package

# Clone the repository
git clone https://github.com/manalejandro/debai.git
cd debai

# Install build dependencies
sudo apt install -y \
    build-essential \
    debhelper \
    dh-python \
    python3-all \
    python3-setuptools

# Build the package
dpkg-buildpackage -us -uc -b

# Install
sudo dpkg -i ../debai_1.0.0-1_all.deb
sudo apt-get install -f

Post-Installation

Initialize Debai

# Basic initialization
debai init

# Full initialization (includes pulling recommended model)
debai init --full

Configure Docker (Required for Models)

# Add your user to docker group
sudo usermod -aG docker $USER

# Restart Docker service
sudo systemctl restart docker

# You may need to log out and back in for group changes to take effect

Verify Installation

# Check version
debai --version

# Show status
debai status

# List available models
debai model list

Enable System Service (Optional)

# Enable Debai service to start on boot
sudo systemctl enable debai

# Start the service
sudo systemctl start debai

# Check status
sudo systemctl status debai

Configuration

User Configuration

Create or edit ~/.config/debai/config.yaml:

general:
  log_level: info

agents:
  max_concurrent: 5
  auto_start: true

models:
  default: llama3.2:3b

System Configuration

Edit /etc/debai/config.yaml for system-wide settings (requires root).

Troubleshooting

Docker Permission Denied

If you get "Permission denied" errors with Docker:

sudo usermod -aG docker $USER
newgrp docker  # Or log out and back in

GTK/GUI Not Working

Install additional GTK dependencies:

sudo apt install -y \
    gir1.2-gtk-4.0 \
    gir1.2-adw-1 \
    python3-gi \
    python3-gi-cairo

Models Not Pulling

Check Docker status:

# Check if Docker is running
sudo systemctl status docker

# Check Docker Model Runner
docker ps | grep model

Import Errors

Ensure all Python dependencies are installed:

pip install -r requirements.txt

Upgrading

Debian Package

# Download new version
wget https://github.com/manalejandro/debai/releases/latest/download/debai_1.0.0-1_all.deb

# Upgrade
sudo dpkg -i debai_1.0.0-1_all.deb

pip

pip install --upgrade debai

From Source

cd debai
git pull
pip install -e .

Uninstallation

Debian Package

# Remove package
sudo apt remove debai

# Remove package and configuration
sudo apt purge debai

pip

pip uninstall debai

Clean Up Data

# Remove user data (optional)
rm -rf ~/.config/debai
rm -rf ~/.local/share/debai

# Remove system data (requires root)
sudo rm -rf /var/lib/debai
sudo rm -rf /etc/debai

Next Steps

After installation:

1. Pull a Model: debai model pull llama3.2:3b
2. Create an Agent: debai agent create --template package_updater
3. Launch GUI: debai-gui
4. Read the User Guide

Getting Help

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions