Installing-groundSwXtch-Air-gapped

WHAT TO EXPECT
In this article, users will learn how to install a groundSwXtch onto a host with no internet access at all (fully air-gapped), by pre-staging the installer, images, and Docker itself on a separate internet-connected staging host and carrying them across on physical or offline media.
For the standard, internet-connected install path, see the Installing groundSwXtch article.

Prerequisites

What is needed:

A staging host with internet access (does not need to be on the same network as the air-gapped target, and does not need a GitHub account, an Azure account, the Azure CLI, or docker login).
The air-gapped target VM/hardware, running Ubuntu 24.04, with no internet access.
The ability to physically transfer files between the two (USB drive, offline media, or a controlled one-way transfer process).
Docker installed and running on both hosts before you run install-groundswxtch.sh.

STEP ONE: Build and download an offline Docker bundle (on the staging host)

Skip this step if Docker is already installed and running on the air-gapped target. Otherwise, build an offline Docker bundle on the staging host by following Build an offline Docker bundle in How to Install Docker on RHEL and Ubuntu.

STEP TWO: Fetch the installer script and images (on the staging host)

groundSwXtch images are distributed over HTTPS from an Azure Blob container, using a read-only SAS token baked into install-groundswxtch.sh. No GitHub account, Azure account, Azure CLI, or docker login is required — do not use docker pull ghcr.io/... directly, that path requires separate GHCR credentials most installs will not have.

BLOB_BASE="https://swxrkdistribution.blob.core.windows.net/swxcontainer01"
RO_SAS='sp=rl&st=2026-05-21T21:40:09Z&se=2027-05-23T05:55:09Z&spr=https&sv=2026-02-06&sr=c&sig=HA9RA9sUQwLBKfePWwB3UhLKGlvtJgoT6z2bCU1Kb6k%3D'
curl -fL "${BLOB_BASE}/install-groundswxtch.sh?${RO_SAS}" -o install-groundswxtch.sh
chmod +x install-groundswxtch.sh

Fetch the image, replacing the version placeholder with your target release version (see the Example below).

sudo ./install-groundswxtch.sh gswx-fetch --image-tag groundswxtch:<version>

Example:

sudo ./install-groundswxtch.sh gswx-fetch --image-tag groundswxtch:v1.0.1

Optional but recommended: fetch swx-tools.

sudo ./install-groundswxtch.sh tools-fetch

The following steps use v1.0.1, but will need to be updated if you used a different version above.

STEP THREE: Export the loaded images to tarballs

Confirm the exact local tags before saving — don't assume version numbers from documentation:

docker image ls | grep -E 'groundswxtch|swx-tools'
docker save groundswxtch:v1.0.1 | gzip > groundswxtch-v1.0.1.tar.gz
docker save swx-tools:1.0.0 | gzip > swx-tools-1.0.0.tar.gz   # if fetched
ls -la *.tar.gz

IMPORTANT
Sanity-check the resulting file sizes — they should be hundreds of MB. A tarball of only a few dozen bytes means docker save failed (usually because the tag didn't match what was actually loaded) and gzip silently wrapped an empty stream into a small but valid-looking .gz file.

STEP FOUR: Transfer everything across the air gap

Carry all of the following together, using your approved offline transfer method:

install-groundswxtch.sh
groundswxtch-v1.0.1.tar.gz
swx-tools-1.0.0.tar.gz (if fetched)
docker-offline-bundle.tar.gz (if Docker is not already installed on the target)

STEP FIVE: Install Docker on the air-gapped host

Skip this step if Docker is already installed and running. Otherwise, install Docker from the bundle you built in STEP ONE by following Install Docker on the air-gapped host in How to Install Docker on RHEL and Ubuntu.

STEP SIX: Load the images and launch groundSwXtch

chmod +x install-groundswxtch.sh
sudo docker load < groundswxtch-v1.0.1.tar.gz
sudo docker image ls | grep -E 'groundswxtch|swx-tools'   # confirm both tags are present
sudo ./install-groundswxtch.sh gswx-run --image-tag groundswxtch:v1.0.1

NOTE
These commands are shown with sudo. If your user is in the docker group you can drop it — just be consistent within a single host.

To also bring up swx-tools for testing, confirm the current subcommand name first, then launch it:

sudo docker load < swx-tools-1.0.0.tar.gz
sudo ./install-groundswxtch.sh -h | grep -i tools
sudo ./install-groundswxtch.sh tools-run --network host

Validate that both groundSwXtch and swx-tools are showing up and running.

docker ps

There should be a line with the name gswx. For example:

CONTAINER ID   IMAGE                 COMMAND           CREATED         STATUS         NAMES
9f9340d96e51   groundswxtch:v1.0.1   "groundswxtchd"   2 minutes ago   Up 2 minutes   gswx
bef02c5593e1   swx-tools:1.0.0       "sleep infinity"  4 minutes ago   Up 4 minutes   swx-tools

STEP SEVEN: License the groundSwXtch

Licensing is fully offline-compatible — the fingerprint pull and reload both hit the container's local API only; the license.key file itself is exchanged with swXtch out-of-band (email, etc.), not fetched automatically.

To license your groundSwXtch see: How to license the groundSwXtch.

NEXT STEPS
The groundSwXtch is ready to use. Two habits worth carrying forward for future air-gapped installs: always confirm exact image tags with docker image ls rather than assuming version numbers from documentation, and always check ./install-groundswxtch.sh -h on the actual host before trusting subcommand names, since they can change between releases.

Documentation Index