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:
- All releases: Releases page
- Latest release: Latest release
| Platform | Architecture | Download |
|---|---|---|
| Linux | amd64 | Download |
| Linux | arm64 | Download |
| macOS | amd64 (Intel) | Download |
| macOS | arm64 (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 replacelatest/downloadin the URL withdownload/<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
| Command | Description |
|---|---|
create | Create an offline bundle on an internet-connected machine |
deploy | Deploy CSGHub from a bundle on an isolated machine |
cleanup | Uninstall K3s and remove all deployed services |
list-images | List the runtime images provided by csghub-server |
4.1 create
sudo csghub-airgap create [options]
| Option | Description |
|---|---|
--output, -o | Bundle output directory. Default: ./csghub-airgap-<date> |
--arch | Target architecture (amd64, arm64). Defaults to the host architecture |
--skip | Skip components: k3s, charts, image, runtime, package, tar, or chart names csghub, longhorn, nvdp |
--proxy | Prefix GitHub downloads with the ghfast.top proxy |
--force-pull | Ignore local image caches and always pull from the registry |
--quiet, -q | Skip interactive prompts (no runtime images are selected) |
--set, -s | Set Helm values (e.g. csghub.key=value, repeatable) |
--k3s-arg / --k3s-env | Extra K3s startup arguments or environment variables |
--dry-run | Print the actions to be performed without executing them |
4.2 deploy
sudo csghub-airgap deploy [options]
| Option | Description |
|---|---|
--input, -i | Bundle directory or .tar file. Default: ./csghub-airgap-<date> |
--domain | CSGHub access domain. Default: csghub.example.com |
--data, -D | Data directory for K3s and Longhorn |
--skip | Same kinds and chart names as create |
--quiet, -q | Skip interactive prompts; stop and disable multipathd automatically |
--set, -s | Override Helm values at deploy time |
--dry-run | Print 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:
cleanupremoves 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 typingyesto confirm.
4.4 list-images
csghub-airgap list-images [options]
| Option | Description |
|---|---|
--source | Configuration source: github (online) or local (local directory, for isolated environments) |
--version, -v | csghub-server Git branch or tag. Default: main |
--local-path | Local csghub-server configuration directory (with --source local) |
--category, -c | Filter by category: evaluation, finetune, inference, job, notebook, space |
--compute | Filter by compute type: cpu, gpu, dcu |
--format, -f | Output 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
deployandcleanuprequire root privileges; on Linux,createalso requires root when downloading NVIDIA packages.- Bundle configuration is stored in
metadata.yamlinside the bundle and applied automatically on deploy. Command-line options can override it at deploy time. - Pulled images are cached under
csghub-airgap/imagesin the user cache directory:~/.cache/csghub-airgap/imageson Linux and~/Library/Caches/csghub-airgap/imageson macOS. The cache is reused when an interrupted run is retried. Use--force-pullto refresh it. - Bundles may contain sensitive configuration. Store them securely and verify their integrity before deployment.
7. Related Links
- GitHub repository: OpenCSGs/csghub-airgap
- Release downloads: GitHub Releases
- Full user guide: USER_GUIDE.md