---
title: "Installing-groundSwXtch-Air-gapped"
slug: "installing-groundswxtch-air-gapped"
updated: 2026-08-17T17:49:50Z
published: 2026-08-17T17:49:50Z
canonical: "docs.swxtch.io/installing-groundswxtch-air-gapped"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swxtch.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing-groundSwXtch-Air-gapped

> [!NOTE]
> 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](/v2/docs/how-to-install-docker-on-rhel-and-ubuntu#build-an-offline-docker-bundle-on-a-staging-host-with-internet-access) in [How to Install Docker on RHEL and Ubuntu](/v2/docs/how-to-install-docker-on-rhel-and-ubuntu#build-an-offline-docker-bundle-on-a-staging-host-with-internet-access).

## **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.

```shell
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).

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

Example:

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

Optional but recommended: fetch swx-tools.

```plaintext
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:

```shell
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
```

> [!CAUTION]
> 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](/v2/docs/how-to-install-docker-on-rhel-and-ubuntu#install-docker-on-the-airgapped-host) in [How to Install Docker on RHEL and Ubuntu](/v2/docs/how-to-install-docker-on-rhel-and-ubuntu#install-docker-on-the-airgapped-host).

## **STEP SIX: Load the images and launch groundSwXtch**

```shell
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]
> 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:

```shell
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.

```shell
docker ps
```

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

```plaintext
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](/v2/docs/how-to-license-the-groundswxtch).

> [!NOTE]
> 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.