Installation

botserver installs itself automatically through the bootstrap process. Just run the binary.

Runtime Dependencies

Before running the botserver binary, you must install required system libraries on the host system.

Quick Install (Recommended)

Download and run the dependency installer:

curl -fsSL https://raw.githubusercontent.com/GeneralBots/botserver/main/scripts/install-dependencies.sh | sudo bash

Or if you have the script locally:

sudo ./scripts/install-dependencies.sh

Manual Install (Debian/Ubuntu)

sudo apt update
sudo apt install -y \
    libpq5 \
    libssl3 \
    liblzma5 \
    zlib1g \
    ca-certificates \
    curl \
    wget \
    libabseil-dev \
    libclang-dev \
    pkg-config

# For container support (LXC)
sudo snap install lxd
sudo lxd init --auto

Manual Install (Fedora/RHEL)

sudo dnf install -y \
    libpq \
    openssl-libs \
    xz-libs \
    zlib \
    ca-certificates \
    curl \
    wget \
    lxc

⚠️ Common Error: If you see error while loading shared libraries: libpq.so.5, install libpq5 (Debian/Ubuntu) or libpq (Fedora/RHEL).

System Requirements

Quick Start

./botserver

The bootstrap process automatically:

1. Detects your system (OS/architecture)
2. Creates botserver-stack/ directory structure
3. Downloads PostgreSQL, Drive, Cache, LLM server
4. Initializes database and storage
5. Deploys default bot
6. Starts all services

First run takes 2-5 minutes.

Using Existing Services

If you have existing infrastructure, configure it in your bot’s config.csv:

name,value
database-url,postgres://myuser:mypass@myhost:5432/mydb
drive-server,http://my-drive:9000
drive-accesskey,my-access-key
drive-secret,my-secret-key

Default Ports

Verify Installation

# Check services
./botserver status

# Test database
psql $DATABASE_URL -c "SELECT version();"

# Test LLM
curl http://localhost:8081/v1/models

# Open UI
open http://localhost:8080

Bot Deployment

Bots deploy to object storage (not local filesystem):

mybot.gbai → creates 'mybot' bucket in drive

The work/ folder is for internal use only.

S3 Sync for Development

Use S3-compatible tools for local editing:

• Cyberduck (GUI)
• rclone (CLI)
• WinSCP (Windows)

# rclone sync example
rclone sync ./mybot.gbai drive:mybot --watch

Edits sync automatically - changes reload without restart.

Memory Optimization

For limited RAM systems:

name,value
llm-server-ctx-size,2048
llm-server-parallel,2

Use quantized models (Q3_K_M, Q4_K_M) for smaller memory footprint.

GPU Setup

For GPU acceleration:

name,value
llm-server-gpu-layers,35

Requires CUDA installed and 12GB+ VRAM.

Deployment Options

Container-on-Host (Brother Mode)

You can run botserver inside a container (Docker/LXC) while letting it manage other containers directly on the host system. This is useful for CI/CD pipelines or managing “host” deployment from a restricted environment.

Requirements:

• Mount host’s LXD socket to container
• Run container as privileged (if accessing host devices)

Docker Run Example:

docker run -d \
  --name botserver \
  --network host \
  --privileged \
  -v /var/lib/lxd/unix.socket:/var/lib/lxd/unix.socket \
  -e VAULT_ADDR="https://127.0.0.1:8200" \
  -e VAULT_TOKEN="<your-token>" \
  botserver:latest

The installer detects if it is running in a container but needs to manage the host (brother mode) and will configure the host’s LXD/LXC environment safely.

⚠️ IMPORTANT: Container create commands (botserver install ... --container) must be run from the host system, not inside a container.

Example: Create Vault and VectorDB

# Run on HOST system
botserver install vault --container --tenant mycompany
botserver install vector_db --container --tenant mycompany

# Verify containers
lxc list | grep mycompany

Troubleshooting

Next Steps

• Quick Start Guide - Create your first bot
• First Conversation - Test your bot
• Configuration Reference - All settings