Skip to main content
Using the ADK in an air-gapped environment introduces additional challenges that you need to address:
  • The ADK Python package is hosted on PyPI, which is inaccessible in an air-gapped environment.
  • By default, watsonx Orchestrate pulls packages from PyPI when installing Python tools.
  • All ADK components must be available in your internal registry, including ibm-watsonx-orchestrate, ibm-watsonx-orchestrate-core, ibm-watsonx-orchestrate-clients, and all transitive dependencies for the target Python runtime version.
Python tool dependencies are installed server-side at deployment time, not during tool import. This means your internal registry must be accessible from watsonx Orchestrate when tools are deployed—specifically, the registry must be reachable from the Tools Runtime Manager and executor runtime inside the cluster, not only from the developer workstation. For comprehensive information on dependency management, see Python dependency management.

​
Prerequisites

As a site administrator, you need:
  • Access to a jumpbox that connects to both the internet and your Cloud Pak for Data cluster
  • A locally hosted Python package registry accessible from your internal network (common PyPI registry providers include Artifactory and Sonatype Nexus)

​
Setting up a jumpbox and local registry

A jumpbox is a machine with access to both the public internet and your internal network. You use it to download packages from PyPI and upload them to your local registry, so watsonx Orchestrate can install them at tool deployment time without needing internet access. The general workflow is:
  1. On the jumpbox (internet access), download all required packages as wheel files.
  2. Upload those wheel files to your local PyPI registry (for example, Artifactory or Nexus).
  3. Configure your tools to reference the local registry in requirements.txt.
The sections below walk through each step in detail.

​
Uploading the ADK to your local PyPI registry

1

Get the dependencies list

On your jumpbox, run the following commands to get the full list of dependencies and generate wheel files for each ADK dependency:
2

Upload wheel files

Upload all generated wheel files from the dependencies directory to your local PyPI registry provider.For Artifactory, you can use twine:
For Nexus, use the REST upload API or the Nexus UI to publish each .whl file to your hosted PyPI repository.
3

Verify packages are available

After uploading, confirm that the packages are reachable from your internal network before importing any tools. Run the following from a machine on the same network as watsonx Orchestrate:
You should see the version you uploaded listed in the output. If no versions appear, check that the upload completed successfully and that the registry URL is correct.You can also verify a specific dependency the same way:

​
Activating the ADK in air-gapped environments

When activating your watsonx Orchestrate environment in an air-gapped setup, use the following flags to prevent external registry access:
Flag explanations:
  • --registry skip: Prevents the ADK CLI from replacing or appending its default registry-based ADK dependency
  • --skip-version-check: Avoids public PyPI version validation during activation

​
Configuring Python tool imports

To import Python tools successfully, configure watsonx Orchestrate to pull the ADK from your local registry. All Python tools must be imported with a requirements.txt file that contains at least the following:
Important: Use --extra-index-url, --index-url, or -i to configure your internal registry. When watsonx Orchestrate detects any of these flags, it automatically removes public PyPI access and pulls packages only from your internal registry. This ensures security compliance in air-gapped environments.After changing requirements.txt or registry configuration, you must reimport the Python tool so watsonx Orchestrate generates a new dependency bundle and dependency hash.
Any dependencies other than the ADK that you want to use in your tools must also be uploaded to your PyPI registry by the site administrator. Remember that dependencies are installed server-side when tools are deployed, so your registry must remain accessible from watsonx Orchestrate.

​
Authenticating to a private registry

Some private registries require authentication. You can embed credentials directly in the requirements.txt index URL:
Some registries (such as GitLab packages) strip the authentication token from dependency download URLs after the initial index lookup. If you get 401 Unauthorized errors when installing packages — even though the index URL works — this is likely the cause.In this case, configure the registry itself to include the token in all redirect URLs, or switch to a registry that preserves authentication through the full download flow (for example, Artifactory or Nexus).

​
Best practices for air-gapped deployments

  1. Pin all dependency versions to ensure reproducible builds. Always pin the ADK version and all application dependencies:
  2. Use hash verification for maximum security:
  3. Lock your internal registry to prevent package changes between environments
  4. Validate your configuration by deploying a test Python tool in the target air-gapped cluster and confirming that package installation succeeds without external network access. This ensures all transitive dependencies are available in your internal registry.
For detailed guidance on enterprise dependency patterns, see Python dependency management.

​
Troubleshooting

​
Tool deployment fails with “package not found” or dependency errors

The tool runtime (TRM) installs packages at deployment time, not at import time. If deployment fails, the most likely cause is that one or more packages are missing from your local registry. To check which packages are missing:
  1. Look at the error message in the tool deployment logs. The missing package name is usually included.
  2. On your jumpbox, confirm the package exists in your local registry:
  3. If the package is not found, download it and upload it to your registry following the same steps as the ADK upload above.
Common causes:
  • A transitive dependency was added in a newer version of a package you rely on. Re-run pip wheel -r requirements.txt on your jumpbox with the updated requirements and re-upload.
  • The requirements.txt in your tool uses --extra-index-url but also still references PyPI for some packages. Make sure all packages are present in your local registry.

​
Tool deployment fails even though packages appear to be in the registry

If packages are uploaded but deployment still fails, check the following:
  1. Registry accessibility: Confirm the registry URL is reachable from the watsonx Orchestrate cluster, not just from the jumpbox. The tool runtime contacts the registry directly during deployment.
  2. TLS / SSL errors: If your registry uses a self-signed or enterprise CA certificate, the tool runtime may fail to validate it. Contact your cluster administrator to ensure the CA certificate is trusted by the watsonx Orchestrate runtime environment.
  3. Registry URL format: Verify that the --extra-index-url value in your requirements.txt ends with /simple/ as required by PEP 503:

​
Authentication errors from a private registry (401 Unauthorized)

If your registry requires authentication and you see 401 Unauthorized errors during tool deployment:
  1. Confirm the credentials embedded in the --extra-index-url are correct and have not expired.
  2. Check whether the registry returns authenticated download URLs. Some registries (such as certain GitLab configurations) return download URLs that do not include authentication tokens, causing the download step to fail even when the index lookup succeeds. In this case, configure the registry to preserve authentication in redirect URLs, or switch to Artifactory or Nexus which handle this correctly.
  3. If using a token in the URL, make sure the token has read access to the package repository.