Skip to main content

Installation Guide

CSGLite provides multiple installation methods and supports cross-platform execution.

System Requirements & Prerequisites​

  • OS: macOS (Apple Silicon / Intel), Linux (x86_64 / ARM64), Windows (x86_64)
  • Inference Dependency: llama-server (Required for local inference; the installation script will attempt to install it automatically)
  • Compilation Dependency: Go 1.22+ (Only required when building from source)

For Linux and macOS, the script automatically detects your system architecture and downloads/installs the tool from GitHub Releases.

curl -fsSL https://hub.opencsg.com/csghub-lite/install.sh | sh

On macOS, the script prioritizes writable directories already in your PATH (such as /opt/homebrew/bin), fallback to ~/bin to avoid using sudo. If it falls back to ~/bin, it will automatically append the path to your shell configuration file and output the command to apply the changes immediately.

Pin a Specific Version​

curl -fsSL https://hub.opencsg.com/csghub-lite/install.sh | CSGHUB_LITE_VERSION=v0.8.55 sh

Enterprise Edition Install (Writes license.txt into the install directory)​

curl -fsSL https://hub.opencsg.com/csghub-lite/install.sh | EE=1 sh

Windows (PowerShell) Installation​

Run the following command in your PowerShell terminal:

$env:EE="1"; irm https://hub.opencsg.com/csghub-lite/install.ps1 | iex

Installer Environment Variables (Optional)​

Both install.sh and install.ps1 support the following optional variables:

VariableDescription
EESet to 1 to write the Enterprise license.txt into the csghub-lite install directory.
INSTALL_DIRCustomize the csghub-lite install directory. On macOS, it defaults to a writable directory in your PATH or falls back to ~/bin. On Linux, it uses the existing install directory or /usr/local/bin.
CSGHUB_LITE_LLAMA_SERVER_INSTALL_DIRCustomize the llama-server install directory. On macOS, it defaults to the same directory as csghub-lite.
CSGHUB_LITE_LLAMA_CPP_TAGSpecify the llama.cpp release tag to install. Defaults to a tag aligned with the built-in convert_hf_to_gguf.py / gguf-py scripts to avoid version mismatches.
CSGHUB_LITE_AUTO_INSTALL_LLAMA_SERVERSet to 0 to skip the automatic installation/upgrade of llama-server.
CSGHUB_LITE_AUTO_INSTALL_PATCHELFOn Linux, set to 0 to disable automatic installation of patchelf (used to set $ORIGIN for llama-server shared objects).
CSGHUB_LITE_LLAMA_ROCM_VERSIONOn Linux, specify the preferred ROCm asset version (e.g. 7.2). Otherwise, the script auto-detects the ROCm environment or falls back to available ROCm/Vulkan/CPU packages.

Method 2: Homebrew (macOS)​

For macOS users, you can install the tool using the following brew commands:

brew tap opencsgs/csghub-lite https://github.com/OpenCSGs/csghub-lite
brew install opencsgs/csghub-lite/csghub-lite

Method 3: GitHub Releases Manual Download​

Go to the Releases page and download the package corresponding to your platform:

PlatformFilename
macOS Apple Siliconcsghub-lite_*_darwin_arm64.tar.gz
macOS Intelcsghub-lite_*_darwin_amd64.tar.gz
Linux x86_64csghub-lite_*_linux_amd64.tar.gz
Linux ARM64csghub-lite_*_linux_arm64.tar.gz
Windows x86_64csghub-lite_*_windows_amd64.zip

Extract the archive and move the binary to a directory in your PATH, for example:

tar xzf csghub-lite_*.tar.gz
mkdir -p "$HOME/bin"
mv csghub-lite "$HOME/bin/"

Method 4: Linux Package Manager​

Debian / Ubuntu​

sudo dpkg -i csghub-lite_*.deb

RHEL / CentOS / Fedora​

sudo rpm -i csghub-lite_*.rpm

Method 5: From Source​

git clone https://github.com/opencsgs/csghub-lite.git
cd csghub-lite
make build
# Binary is at bin/csghub-lite

To compile for all platforms:

make build-all

Installing Inference Backend (llama-server)​

CSGLite uses llama.cpp's llama-server to run local models. If you build from source or did not use the installation script, ensure you install it manually:

macOS​

brew install llama.cpp

Linux / Windows​

Download the precompiled packages from the llama.cpp Releases and add llama-server to your PATH.

# Example: Linux x86_64
wget https://github.com/ggml-org/llama.cpp/releases/download/b9158/llama-b9158-bin-ubuntu-x64.tar.gz
tar xzf llama-b9158-bin-ubuntu-x64.tar.gz
sudo cp build/bin/llama-server /usr/local/bin/

Verify Installation​

csghub-lite --version
llama-server --version

Running with Docker (Docker Runtime Images)​

CSGLite publishes container images as lightweight bootstrap runtimes. They contain the base OS and GPU driver requirements. On startup, they automatically download csghub-lite and the matching llama-server based on environment variables.

[!IMPORTANT] Always mount a host directory to /root/.csghub-lite inside the container. This ensures that downloaded models, settings, credentials, and engines survive container restarts and updates.

Official Images​

ImagePurpose
opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite:latestStandard Linux CPU/GPU runtime
opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite-rocm:latestAMD GPU hosts with ROCm support

Docker Install Policy & Configuration Variables​

Environment variableDescription
CSGHUB_LITE_VERSIONPin the csghub-lite version, e.g. v0.8.55.
CSGHUB_LITE_LLAMA_CPP_TAGPin the llama.cpp engine tag, e.g. b9158.
CSGHUB_LITE_INSTALL_POLICYInstall policy: if-missing (default), if-version-mismatch, or always.
CSGHUB_LITE_INSTALL_ALWAYSSet to 1 to force re-installing binaries on container start.
CSGHUB_LITE_INSTALL_URLOverride download URL for private repository mirrors.
CSGHUB_LITE_REGIONLimit download region, e.g. CN or INTL.
CSGHUB_LITE_REQUIRE_LLAMA_SERVERSet to 0 to run in cloud-only mode without downloading a local inference engine.

Docker Examples​

1. Standard CPU/GPU Runtime​

mkdir -p ~/.csghub-lite-docker

docker run -d --name csghub-lite \
  -p 11435:11435 \
  -v ~/.csghub-lite-docker:/root/.csghub-lite \
  opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite:latest

2. Version Lock & Alignment​

docker run -d --name csghub-lite \
  -p 11435:11435 \
  -e CSGHUB_LITE_VERSION=v0.8.55 \
  -e CSGHUB_LITE_LLAMA_CPP_TAG=b9158 \
  -e CSGHUB_LITE_INSTALL_POLICY=if-version-mismatch \
  -v csghub-lite-data:/root/.csghub-lite \
  opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite:latest

3. Force Upgrade on Startup​

docker run -d --name csghub-lite \
  -p 11435:11435 \
  -e CSGHUB_LITE_INSTALL_ALWAYS=1 \
  -v csghub-lite-data:/root/.csghub-lite \
  opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite:latest

4. AMD ROCm GPU Hosts​

docker run -d --name csghub-lite-rocm \
  --device=/dev/kfd \
  --device=/dev/dri \
  --group-add video \
  --ipc=host \
  --security-opt seccomp=unconfined \
  -p 11435:11435 \
  -e CSGHUB_LITE_VERSION=v0.8.52 \
  -v csghub-lite-data:/root/.csghub-lite \
  opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/csghub-lite-rocm:latest

Note: The ROCm image includes a prebuilt Python conversion environment (PyTorch, safetensors, transformers, sentencepiece). On first container start, the entrypoint will seed that environment into /root/.csghub-lite/tools/python if the mounted volume is empty.