291
docs/INSTALLATION.md
Archivo normal
291
docs/INSTALLATION.md
Archivo normal
@@ -0,0 +1,291 @@
|
||||
# Installation Guide
|
||||
|
||||
This guide provides detailed instructions for installing Debai on your GNU/Linux system.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### System Requirements
|
||||
|
||||
- **Operating System**: Debian 12 (Bookworm) or newer, Ubuntu 22.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
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y \
|
||||
python3 \
|
||||
python3-pip \
|
||||
python3-venv \
|
||||
python3-gi \
|
||||
gir1.2-gtk-4.0 \
|
||||
gir1.2-adw-1
|
||||
```
|
||||
|
||||
#### Recommended
|
||||
|
||||
```bash
|
||||
sudo apt install -y \
|
||||
docker.io \
|
||||
qemu-utils \
|
||||
genisoimage
|
||||
```
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### Method 1: Debian Package (Recommended)
|
||||
|
||||
Download and install the `.deb` package:
|
||||
|
||||
```bash
|
||||
# Download the latest release
|
||||
wget https://github.com/debai/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
|
||||
|
||||
```bash
|
||||
# Install from PyPI
|
||||
pip install debai
|
||||
|
||||
# Or with GUI support
|
||||
pip install debai[gui]
|
||||
```
|
||||
|
||||
### Method 3: From Source
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/debai/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
|
||||
|
||||
```bash
|
||||
# Basic initialization
|
||||
debai init
|
||||
|
||||
# Full initialization (includes pulling recommended model)
|
||||
debai init --full
|
||||
```
|
||||
|
||||
### Configure Docker (Required for Models)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Check version
|
||||
debai --version
|
||||
|
||||
# Show status
|
||||
debai status
|
||||
|
||||
# List available models
|
||||
debai model list
|
||||
```
|
||||
|
||||
### Enable System Service (Optional)
|
||||
|
||||
```bash
|
||||
# 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`:
|
||||
|
||||
```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:
|
||||
|
||||
```bash
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker # Or log out and back in
|
||||
```
|
||||
|
||||
### GTK/GUI Not Working
|
||||
|
||||
Install additional GTK dependencies:
|
||||
|
||||
```bash
|
||||
sudo apt install -y \
|
||||
gir1.2-gtk-4.0 \
|
||||
gir1.2-adw-1 \
|
||||
python3-gi \
|
||||
python3-gi-cairo
|
||||
```
|
||||
|
||||
### Models Not Pulling
|
||||
|
||||
Check Docker status:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Upgrading
|
||||
|
||||
### Debian Package
|
||||
|
||||
```bash
|
||||
# Download new version
|
||||
wget https://github.com/debai/debai/releases/latest/download/debai_1.0.0-1_all.deb
|
||||
|
||||
# Upgrade
|
||||
sudo dpkg -i debai_1.0.0-1_all.deb
|
||||
```
|
||||
|
||||
### pip
|
||||
|
||||
```bash
|
||||
pip install --upgrade debai
|
||||
```
|
||||
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
cd debai
|
||||
git pull
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
## Uninstallation
|
||||
|
||||
### Debian Package
|
||||
|
||||
```bash
|
||||
# Remove package
|
||||
sudo apt remove debai
|
||||
|
||||
# Remove package and configuration
|
||||
sudo apt purge debai
|
||||
```
|
||||
|
||||
### pip
|
||||
|
||||
```bash
|
||||
pip uninstall debai
|
||||
```
|
||||
|
||||
### Clean Up Data
|
||||
|
||||
```bash
|
||||
# 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](USER_GUIDE.md)
|
||||
|
||||
## Getting Help
|
||||
|
||||
- 📚 [Documentation](https://debai.readthedocs.io)
|
||||
- 🐛 [Issue Tracker](https://github.com/debai/debai/issues)
|
||||
- 💬 [Discussions](https://github.com/debai/debai/discussions)
|
||||
172
docs/debai.1
Archivo normal
172
docs/debai.1
Archivo normal
@@ -0,0 +1,172 @@
|
||||
.\" Manpage for debai
|
||||
.\" Contact debai@example.com for errors or typos.
|
||||
.TH DEBAI 1 "January 2026" "Debai 1.0.0" "User Commands"
|
||||
.SH NAME
|
||||
debai \- AI Agent Management System for GNU/Linux
|
||||
.SH SYNOPSIS
|
||||
.B debai
|
||||
[\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS\fR]...
|
||||
.SH DESCRIPTION
|
||||
.B debai
|
||||
is a comprehensive application for generating and managing AI agents that automate system tasks like package updates, application configuration, and resource management.
|
||||
.PP
|
||||
Debai uses local AI models via Docker Model Runner and local agents via cagent. It provides both a command-line interface and a graphical user interface (GTK4/Adwaita).
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.BR \-v ", " \-\-verbose
|
||||
Enable verbose output with debug information.
|
||||
.TP
|
||||
.BR \-c ", " \-\-config " " \fIFILE\fR
|
||||
Use specified configuration file instead of default.
|
||||
.TP
|
||||
.BR \-\-version
|
||||
Show version information and exit.
|
||||
.TP
|
||||
.BR \-\-help
|
||||
Show help message and exit.
|
||||
.SH COMMANDS
|
||||
.SS "General Commands"
|
||||
.TP
|
||||
.B status
|
||||
Show system and Debai status, including dependencies and Docker information.
|
||||
.TP
|
||||
.B init [\-\-full]
|
||||
Initialize Debai environment. Use \-\-full to also pull recommended models.
|
||||
.TP
|
||||
.B monitor [\-i INTERVAL]
|
||||
Monitor system resources in real-time. Default interval is 2 seconds.
|
||||
.SS "Agent Commands"
|
||||
.TP
|
||||
.B agent list [\-s STATUS]
|
||||
List all agents. Filter by status: running, stopped, or all.
|
||||
.TP
|
||||
.B agent create \-n NAME [\-t TYPE] [\-m MODEL] [\-\-template NAME]
|
||||
Create a new agent. Available types: system, package, config, resource, security, backup, network, custom.
|
||||
.TP
|
||||
.B agent start AGENT_ID
|
||||
Start an agent.
|
||||
.TP
|
||||
.B agent stop AGENT_ID
|
||||
Stop an agent.
|
||||
.TP
|
||||
.B agent delete AGENT_ID [\-f]
|
||||
Delete an agent. Use \-f to skip confirmation.
|
||||
.TP
|
||||
.B agent chat AGENT_ID
|
||||
Start an interactive chat session with an agent.
|
||||
.TP
|
||||
.B agent templates
|
||||
List available agent templates.
|
||||
.SS "Model Commands"
|
||||
.TP
|
||||
.B model list
|
||||
List available models.
|
||||
.TP
|
||||
.B model pull MODEL_ID
|
||||
Pull a model from Docker Model Runner.
|
||||
.TP
|
||||
.B model remove MODEL_ID [\-f]
|
||||
Remove a model. Use \-f to skip confirmation.
|
||||
.TP
|
||||
.B model recommended
|
||||
Show recommended models for different use cases.
|
||||
.SS "Task Commands"
|
||||
.TP
|
||||
.B task list [\-s STATUS]
|
||||
List all tasks. Filter by status: pending, running, completed, failed, or all.
|
||||
.TP
|
||||
.B task create \-n NAME \-c COMMAND [\-p PRIORITY] [\-\-template NAME]
|
||||
Create a new task.
|
||||
.TP
|
||||
.B task run TASK_ID
|
||||
Run a task immediately.
|
||||
.TP
|
||||
.B task templates
|
||||
List available task templates.
|
||||
.SS "Generate Commands"
|
||||
.TP
|
||||
.B generate iso [\-o OUTPUT] [\-\-base DISTRO] [\-\-include\-agents]
|
||||
Generate a bootable ISO image with Debai pre-installed.
|
||||
.TP
|
||||
.B generate qcow2 [\-o OUTPUT] [\-\-size SIZE] [\-\-base DISTRO]
|
||||
Generate a QCOW2 disk image for QEMU/KVM.
|
||||
.TP
|
||||
.B generate compose [\-o OUTPUT] [\-\-include\-gui]
|
||||
Generate a Docker Compose configuration.
|
||||
.SH EXAMPLES
|
||||
.PP
|
||||
Initialize Debai and pull a model:
|
||||
.RS
|
||||
.nf
|
||||
$ debai init --full
|
||||
.fi
|
||||
.RE
|
||||
.PP
|
||||
Create an agent from template:
|
||||
.RS
|
||||
.nf
|
||||
$ debai agent create --name "Updates" --template package_updater
|
||||
.fi
|
||||
.RE
|
||||
.PP
|
||||
Chat with an agent:
|
||||
.RS
|
||||
.nf
|
||||
$ debai agent chat abc123
|
||||
.fi
|
||||
.RE
|
||||
.PP
|
||||
Generate an ISO image:
|
||||
.RS
|
||||
.nf
|
||||
$ debai generate iso --output debai.iso --include-agents
|
||||
.fi
|
||||
.RE
|
||||
.SH FILES
|
||||
.TP
|
||||
.I /etc/debai/config.yaml
|
||||
System-wide configuration file.
|
||||
.TP
|
||||
.I ~/.config/debai/
|
||||
User configuration directory.
|
||||
.TP
|
||||
.I /var/lib/debai/
|
||||
Data directory for agents, models, and tasks.
|
||||
.TP
|
||||
.I /var/log/debai/
|
||||
Log files directory.
|
||||
.SH ENVIRONMENT
|
||||
.TP
|
||||
.B DEBAI_CONFIG_DIR
|
||||
Override the configuration directory.
|
||||
.TP
|
||||
.B DEBAI_DATA_DIR
|
||||
Override the data directory.
|
||||
.TP
|
||||
.B DEBAI_LOG_LEVEL
|
||||
Set the logging level (debug, info, warning, error).
|
||||
.SH EXIT STATUS
|
||||
.TP
|
||||
.B 0
|
||||
Success.
|
||||
.TP
|
||||
.B 1
|
||||
General error.
|
||||
.TP
|
||||
.B 2
|
||||
Command line syntax error.
|
||||
.SH SEE ALSO
|
||||
.BR debai-gui (1),
|
||||
.BR docker (1),
|
||||
.BR qemu-img (1),
|
||||
.BR systemctl (1)
|
||||
.SH BUGS
|
||||
Report bugs at: https://github.com/debai/debai/issues
|
||||
.SH AUTHOR
|
||||
Debai Team <debai@example.com>
|
||||
.SH COPYRIGHT
|
||||
Copyright \(co 2025-2026 Debai Team.
|
||||
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
|
||||
.PP
|
||||
This is free software: you are free to change and redistribute it.
|
||||
There is NO WARRANTY, to the extent permitted by law.
|
||||
Referencia en una nueva incidencia
Block a user