Skip to main content

Usage Guide

1. Overview​

csghub-airgap is a command-line tool provided by CSGHub for creating and deploying CSGHub offline bundles. create can only run in an environment with internet access, where it bundles K3s, Helm charts, and container images. After transferring the artifacts to the isolated network, run deploy on the internal machine. The tool is a pure CLI and does not run any background daemon.

Use cases:

  • Deployment into fully isolated internal networks;
  • Fast offline delivery of CSGHub and its dependencies to a small number of machines;
  • Reusing an existing K3s cluster to import images or install charts only.

2. Download and Install​

Get the binary for your platform from GitHub Releases:

PlatformArchitectureDownload
Linuxamd64Download
Linuxarm64Download
macOSamd64 (Intel)Download
macOSarm64 (Apple Silicon)Download

Checksums: checksums.txt

Install on Linux amd64:

# Download the binary and checksums
curl -fL -O https://github.com/OpenCSGs/csghub-airgap/releases/latest/download/csghub-airgap-linux-amd64
curl -fL -O https://github.com/OpenCSGs/csghub-airgap/releases/latest/download/checksums.txt

# Verify integrity
sha256sum -c checksums.txt --ignore-missing

# Install
chmod +x csghub-airgap-linux-amd64
sudo mv csghub-airgap-linux-amd64 /usr/local/bin/csghub-airgap
csghub-airgap --version

To pin a version, select the corresponding tag (for example v2.2.5) on the Releases page and replace latest/download in the URL with download/<version>.

3. Quick Start​

3.1 Create a bundle on a connected machine​

sudo csghub-airgap create --output /opt/csghub-bundle

create downloads components such as K3s, Helm charts, and container images. When processing the csghub chart, it shows a runtime image selection UI and exports the selected images. When finished, /opt/csghub-bundle.tar is created next to the output directory by default (not created with --skip tar).

3.2 Transfer and deploy on the isolated machine​

# Copy the bundle to the isolated machine
scp /opt/csghub-bundle.tar user@airgap-host:/root/

# Deploy on the isolated machine (unpacked automatically)
sudo csghub-airgap deploy \
--input /opt/csghub-bundle.tar \
--domain csghub.internal.example.com

4. Commands​

CommandDescription
createCreate an offline bundle on an internet-connected machine
deployDeploy CSGHub from a bundle on an isolated machine
cleanupUninstall K3s and remove all deployed services
list-imagesList the runtime images provided by csghub-server

4.1 create​

sudo csghub-airgap create [options]
OptionDescription
--output, -oBundle output directory. Default: ./csghub-airgap-<date>
--archTarget architecture (amd64, arm64). Defaults to the host architecture
--skipSkip components: k3s, charts, image, runtime, package, tar, or chart names csghub, longhorn, nvdp
--proxyPrefix GitHub downloads with the ghfast.top proxy
--force-pullIgnore local image caches and always pull from the registry
--quiet, -qSkip interactive prompts (no runtime images are selected)
--set, -sSet Helm values (e.g. csghub.key=value, repeatable)
--k3s-arg / --k3s-envExtra K3s startup arguments or environment variables
--dry-runPrint the actions to be performed without executing them

4.2 deploy​

sudo csghub-airgap deploy [options]
OptionDescription
--input, -iBundle directory or .tar file. Default: ./csghub-airgap-<date>
--domainCSGHub access domain. Default: csghub.example.com
--data, -DData directory for K3s and Longhorn
--skipSame kinds and chart names as create
--quiet, -qSkip interactive prompts; stop and disable multipathd automatically
--set, -sOverride Helm values at deploy time
--dry-runPrint the actions to be performed without executing them

Before deploying, the tool checks that the operating system and bundle architecture match, and automatically disables the nvdp chart when no NVIDIA GPU is detected.

4.3 cleanup​

sudo csghub-airgap cleanup [--yes]

Warning: cleanup removes the entire machine's k3s installation and all its data, including /var/lib/rancher/k3s, /var/lib/kubelet, the k3s binary, and the systemd service — not just CSGHub resources. If k3s on the machine was installed by you rather than by this tool, it will be removed as well. Proceed with caution. Interactive mode requires typing yes to confirm.

4.4 list-images​

csghub-airgap list-images [options]
OptionDescription
--sourceConfiguration source: github (online) or local (local directory, for isolated environments)
--version, -vcsghub-server Git branch or tag. Default: main
--local-pathLocal csghub-server configuration directory (with --source local)
--category, -cFilter by category: evaluation, finetune, inference, job, notebook, space
--computeFilter by compute type: cpu, gpu, dcu
--format, -fOutput format: table or json

5. Common Scenarios​

5.1 GPU environment​

# Build the bundle (includes nvdp and NVIDIA packages)
sudo csghub-airgap create --output /opt/csghub-gpu

# Deploy (nvdp is installed automatically when a GPU is detected; disabled otherwise)
sudo csghub-airgap deploy \
--input /opt/csghub-gpu \
--domain csghub.gpu.example.com

5.2 Import images only (reuse an existing K3s cluster)​

# Connected machine: export images only
sudo csghub-airgap create --output /opt/csghub-img --skip k3s,charts,package

# Target machine: K3s already installed, import images only
sudo csghub-airgap deploy --input /opt/csghub-img --skip k3s,charts

5.3 Redeploy​

sudo csghub-airgap cleanup --yes
sudo csghub-airgap deploy --input /opt/csghub-bundle --domain csghub.example.com

6. Notes​

  • deploy and cleanup require root privileges; on Linux, create also requires root when downloading NVIDIA packages.
  • Bundle configuration is stored in metadata.yaml inside the bundle and applied automatically on deploy. Command-line options can override it at deploy time.
  • Pulled images are cached under csghub-airgap/images in the user cache directory: ~/.cache/csghub-airgap/images on Linux and ~/Library/Caches/csghub-airgap/images on macOS. The cache is reused when an interrupted run is retried. Use --force-pull to refresh it.
  • Bundles may contain sensitive configuration. Store them securely and verify their integrity before deployment.