How to Install nWave on an Air-Gapped Machine

Who This Is For

This guide is for developers in government, military, or corporate-hardened environments where target machines have no access to PyPI or the internet. It assumes you know Python and have Claude Code installed or know how to install it via your organization's approved mechanism.

How It Works

You build a self-contained bundle on a connected machine, transfer it to the target, and run a single install script. The bundle includes the nWave CLI wheel, all Python dependencies, and the nWave framework assets. No network calls happen during install.

connected machine          transfer          air-gapped target
      |                      |                      |
build bundle  ------> scp / USB / etc. ------> unpack + run install-offline.sh

Build the Bundle

Prerequisites on the connected machine: Python 3.10+, pip, and either uv or pipx.

From the root of the nWave-dev repository, run:

python scripts/build_offline_bundle.py

Expected output:

[INFO] Bundle created: dist/releases/nwave-offline-bundle-2.17.5.tar.gz
[INFO] SHA256: a3f1c2d4e5...
[INFO] Companion: dist/releases/nwave-offline-bundle-2.17.5.tar.gz.sha256

The tarball is placed at dist/releases/nwave-offline-bundle-{version}.tar.gz. Bundle size varies with the dependency tree; expect under 100 MB for typical builds.

The build script also writes a companion checksum file at dist/releases/nwave-offline-bundle-{version}.tar.gz.sha256. Keep both files together during transfer.

Platform note: The optional --python flag selects which Python interpreter runs pip download. It does not change the target platform. Wheels fetched will always match the builder machine's OS and CPU architecture. To target a different platform, build on a machine whose OS, architecture, and Python minor version match the target.

Transfer the Bundle

Use whatever transfer mechanism your organization approves: scp, USB drive, internal file server, or encrypted email attachment.

# Example: scp to target
scp dist/releases/nwave-offline-bundle-2.17.5.tar.gz \
    dist/releases/nwave-offline-bundle-2.17.5.tar.gz.sha256 \
    user@target-host:/tmp/

Verify the checksum on the target before proceeding:

sha256sum -c nwave-offline-bundle-2.17.5.tar.gz.sha256
# Expected: nwave-offline-bundle-2.17.5.tar.gz: OK

Install on the Target Machine

Unpack the bundle into a dedicated directory:

mkdir nwave-bundle && tar -xzf nwave-offline-bundle-2.17.5.tar.gz -C nwave-bundle
cd nwave-bundle

The tarball extracts directly into the target directory (there is no wrapper subdirectory inside the archive).

Run the install script:

./install-offline.sh

The script installs the nwave-ai CLI from the bundled wheels using pip install --no-index --find-links wheels/, then calls nwave-ai install to deploy agents, commands, skills, and DES hooks into ~/.claude/.

Verify the installation:

nwave-ai doctor

Verification

A healthy offline install produces output similar to:

nWave Doctor
============
CLI version       2.17.5       OK
Framework assets  installed    OK
DES hooks         registered   OK
Shims             present      OK
Claude Code       found        OK
Network check     skipped (offline mode)

All checks passed.

Key items to confirm:

CLI version: matches the bundle version you built
Framework assets: agents, commands, and skills are in ~/.claude/
DES hooks: pre-tool-use, post-tool-use, and subagent-stop hooks are registered in ~/.claude/settings.json
Shims: the Python shim wrappers that invoke DES are present and executable
Claude Code: the claude binary is on PATH; if not, Claude Code is not installed (see Limitations)

Restart Claude Code after a successful install. You should see nWave ready in your session context.

Troubleshooting

`pip install --no-index` fails

The wheels directory is missing a required wheel or contains wheels built for the wrong platform.

Check: Confirm all wheels are present for your Python version and platform.

ls wheels/
pip install --no-index --find-links wheels/ nwave-ai --dry-run

If wheels are missing, rebuild the bundle on a connected machine that matches the target's OS and Python version. See Platform constraints below.

`nwave-ai install` fails

Claude Code is not installed on the target machine. The bundle does not ship Claude Code; that is out of scope and must be installed via your organization's approved mechanism.

Check: Confirm claude is on PATH.

which claude
claude --version

If Claude Code is absent, install it first, then rerun nwave-ai install.

`nwave-ai doctor` reports DES hook failures or missing shims

The install script ran but the DES hook registration step did not complete. This can happen if ~/.claude/settings.json was locked or Claude Code was running during install.

Fix: Close Claude Code and rerun the registration step:

nwave-ai install

Then reopen Claude Code and run nwave-ai doctor again.

Bundle is too large

The bundle includes all transitive dependencies. There is currently no automated way to strip optional dependencies. This is a known limitation. If bundle size is a hard constraint, open an issue in the nWave repo to track a slimmed-bundle option.

Python version or platform mismatch

Wheels are platform-specific. A bundle built on Linux x86_64 will not install on macOS ARM, and vice versa. Build the bundle on a machine whose OS, CPU architecture, and Python minor version match the target.

Connected machine    Target machine      Result
Linux x86_64 3.11    Linux x86_64 3.11   OK
Linux x86_64 3.11    Linux x86_64 3.12   Likely fails (ABI mismatch)
Linux x86_64 3.11    macOS ARM 3.11      Fails (platform mismatch)

Build one bundle per distinct target environment.

Limitations

Claude Code is not included. The bundle only covers nWave and its Python dependencies. Claude Code must be installed on the target via its own offline or enterprise mechanism before running nwave-ai install.
Platform-specific wheels. Bundles are not cross-platform. Build a separate bundle for each OS and CPU architecture you need to support.
No automatic updates. Air-gapped machines cannot receive update notifications. Distribute updated bundles manually when a new nWave version is released.
Corporate proxy or TLS interception. Transfer may still be blocked by DLP or firewall rules. Use your organization's approved transfer channel.

Security Considerations

Verify tarball integrity using the .sha256 companion file before unpacking on the target (see Transfer section above).
Audit wheels before install. The wheels/ directory contains all Python packages the installer will execute. You can inspect them with pip show --files <package> on a sandboxed machine before approving the bundle for distribution.
No network calls during install. install-offline.sh uses pip install --no-index exclusively. No package index or CDN is contacted at any point during installation.
DES hooks run as the installing user. The hooks are Python scripts invoked by Claude Code under your user account. They do not require elevated privileges and do not persist as system services.