For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Install Solo Enterprise for agentregistry in an air-gapped environment by mirroring images and binaries to a private registry.

Install Solo Enterprise for agentregistry in an air-gapped environment, such as an on-premises datacenter or a disconnected cluster that cannot pull images, binaries, or Helm charts from public registries or artifact stores.

An airgap installation consists of three phases:

1. Pull artifacts: From a workstation or CI job that can reach both the public artifact sources and your private registry, collect and mirror every required image, binary, and Helm chart for one Solo Enterprise for agentregistry version.
2. Transfer: Copy the mirrored artifacts and Helm chart package to the disconnected environment by using your approved transfer process.
3. Disconnected install: Install the Helm chart with an air-gapped values file that references only your internal artifact locations.

Before you begin

1. Install the following CLIs in a workstation that can reach the public artifact sources and your private registry.

   • helm: Pull and install the Solo Enterprise for agentregistry Helm chart.
   • kubectl: Interact with your Kubernetes cluster.
   • A tool to copy container images between registries, such as crane, skopeo, or docker. The examples in this guide use crane.

2. Set up a private OCI registry that is reachable from your disconnected cluster, such as Amazon ECR, Harbor, or Artifactory. The examples in this guide use a private Amazon ECR registry.

3. Set up an internal artifact endpoint to host the Solo Enterprise for agentregistry runtime binaries, such as an internal HTTPS service or a private S3 bucket that is reachable from pods in the cluster.

4. Get a Solo Enterprise for agentregistry license key. To obtain the key, contact an account representative.

5. Set up an OIDC identity provider, such as Keycloak, that is reachable from pods in the cluster. Solo Enterprise for agentregistry does not bundle its own identity provider. Instead, it relies on an external OIDC provider to authenticate users, issue access tokens, and enforce role-based access control. You must create OIDC clients for different components of Solo Enterprise for agentregistry. For more information and example setup, see the Keycloak guide.

6. Prepare an air-gapped Kubernetes cluster, such as Amazon EKS. For private clusters that pull images from a private registry, your network typically must allow the cluster to reach the registry. For example, an air-gapped EKS cluster that pulls from a private ECR registry usually requires the following VPC endpoints:

   • Interface endpoint: com.amazonaws.<region>.ecr.api
   • Interface endpoint: com.amazonaws.<region>.ecr.dkr
   • Gateway endpoint: com.amazonaws.<region>.s3
   • Private DNS enabled for the ECR interface endpoints
   • If you use EKS Pod Identity or IRSA, an com.amazonaws.<region>.sts interface endpoint.

   Note

   If Solo Enterprise for agentregistry calls other AWS services from the air-gapped cluster, such as AWS Bedrock, Secrets Manager, or CloudWatch Logs, add VPC endpoints for those services too.

Step 1: Identify the version and artifacts

1. Choose the Solo Enterprise for agentregistry version that you want to install, such as the latest patch version (2026.8.0). To find available versions, review the release page and the changelogs.

2. On your connected workstation, set the version and your private registry details as environment variables. The image and binary tags use a v prefix (for example, v2026.8.0), but the Helm chart version does not (for example, 2026.8.0).

   export ARE_VERSION=v2026.8.0
   export CHART_VERSION=2026.8.0
   export AWS_REGION=<region>
   export AWS_ACCOUNT_ID=<account-id>
   export PRIVATE_REGISTRY="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"

3. Review the following container image, binary, and Helm chart artifacts that you must mirror for your configuration. Some images are required only for certain features.

Container images

Solo Enterprise for agentregistry uses the following container images.

Runtime binaries

Solo Enterprise for agentregistry uses the following runtime binaries for managed backend flows, hosted on your internal artifact endpoint.

CLI binary

Solo Enterprise for agentregistry uses the following CLI binary for operators and CI. A .sha256 checksum is published alongside each binary.

Helm chart

Solo Enterprise for agentregistry uses the following Helm chart. The published chart already bundles the ClickHouse subchart, so you do not need to run helm dependency build in the air-gapped environment.

Step 2: Mirror the container images

1. Authenticate to your private registry. For Amazon ECR:

   aws ecr get-login-password --region "${AWS_REGION}" \
     | docker login --username AWS --password-stdin "${PRIVATE_REGISTRY}"

2. Create the destination repositories if they do not already exist. For Amazon ECR:

   aws ecr create-repository --repository-name agentregistry-enterprise/server || true
   aws ecr create-repository --repository-name agentregistry-enterprise/postgres || true
   aws ecr create-repository --repository-name agentregistry-enterprise/clickhouse-server || true
   aws ecr create-repository --repository-name agentregistry-enterprise/opentelemetry-collector-contrib || true

3. Mirror the images that your configuration requires. The server image is always required. Mirror the PostgreSQL, ClickHouse, and OpenTelemetry collector images only if you enable those features.

   # Always required: registry server
   crane copy \
     "us-docker.pkg.dev/solo-public/agentregistry-enterprise/server:${ARE_VERSION}" \
     "${PRIVATE_REGISTRY}/agentregistry-enterprise/server:${ARE_VERSION}"
   
   # Only if you use the bundled PostgreSQL database
   crane copy \
     "docker.io/library/postgres:18" \
     "${PRIVATE_REGISTRY}/agentregistry-enterprise/postgres:18"
   
   # Only if ClickHouse observability is enabled
   crane copy \
     "docker.io/clickhouse/clickhouse-server:26.2.5-alpine" \
     "${PRIVATE_REGISTRY}/agentregistry-enterprise/clickhouse-server:26.2.5-alpine"
   
   # Only if telemetry is enabled
   crane copy \
     "docker.io/otel/opentelemetry-collector-contrib:0.148.0" \
     "${PRIVATE_REGISTRY}/agentregistry-enterprise/opentelemetry-collector-contrib:0.148.0"

Step 3: Mirror the binaries

1. Download the runtime binaries at the same version as the server. These binaries are used by managed backend flows, and the server pod must be able to reach them from your internal artifact endpoint.

   mkdir -p "offline-bundle/binaries/${ARE_VERSION}"
   
   for bin in agentgateway agw-sync agentregistry-sts; do
     curl -fL \
       "https://storage.googleapis.com/agentregistry-enterprise/${ARE_VERSION}/${bin}" \
       -o "offline-bundle/binaries/${ARE_VERSION}/${bin}"
   done
   
   chmod 0755 "offline-bundle/binaries/${ARE_VERSION}/"*

2. Publish the runtime binaries to your internal artifact endpoint so that the path matches <binaryHost>/<binaryBucket>/<version>/<binary>. For example, if you set binaryHost to https://artifacts.internal.example.com and binaryBucket to agentregistry-enterprise, publish the binaries so that the agentgateway binary is reachable at https://artifacts.internal.example.com/agentregistry-enterprise/v2026.8.0/agentgateway. Common options are an internal HTTPS service or a private S3 bucket with an S3 VPC endpoint.

3. Download the arctl CLI binary and its checksum for each platform that your operators or CI pipelines use. Replace <os> (linux or darwin) and <arch> (amd64 or arm64) with your platform.

   curl -fLO "https://storage.googleapis.com/agentregistry-enterprise/${ARE_VERSION}/arctl-<os>-<arch>"
   curl -fLO "https://storage.googleapis.com/agentregistry-enterprise/${ARE_VERSION}/arctl-<os>-<arch>.sha256"

4. Transfer the arctl binary to your operators or an internal artifact endpoint. To install it, verify the download against its checksum, place the binary on the PATH, and make it executable.

   shasum -a 256 -c "arctl-<os>-<arch>.sha256"
   
   mkdir -p $HOME/.arctl/bin
   mv arctl-<os>-<arch> $HOME/.arctl/bin/arctl
   chmod +x $HOME/.arctl/bin/arctl
   export PATH=$HOME/.arctl/bin:$PATH

5. Verify that the arctl CLI is installed.

   arctl version

Step 4: Pull the Helm chart

1. On your connected workstation, pull the Helm chart package. The published chart bundles the ClickHouse subchart, so no additional Helm chart is required.

   helm pull oci://us-docker.pkg.dev/solo-public/agentregistry-enterprise/helm/agentregistry-enterprise \
     --version ${CHART_VERSION} \
     --destination offline-bundle

2. Copy the offline-bundle directory to your air-gapped environment by using your approved transfer process.

Step 5: Create the namespace and secrets

In the air-gapped environment, prepare the namespace and any secrets that your configuration requires.

1. Create the namespace.

   kubectl create namespace agentregistry-system

2. Create the license secret.

   kubectl -n agentregistry-system create secret generic enterprise-agentregistry-license \
     --from-literal=enterprise-agentregistry-license-key='<license-key>'

3. If you use an external (BYO) PostgreSQL database, create a secret with the database connection URL. For other options, see BYO PostgreSQL database.

   kubectl -n agentregistry-system create secret generic agentregistry-postgres \
     --from-literal=AGENT_REGISTRY_DATABASE_URL='postgres://<user>:<password>@<host>:5432/<database>?sslmode=require'

4. If you use private Git repositories for catalog content, create a Git credential secret.

   kubectl -n agentregistry-system create secret generic agentregistry-git \
     --from-literal=GIT_USERNAME='<username>' \
     --from-literal=GIT_TOKEN='<token-or-password>'

Step 6: Create the air-gapped values file

Create an airgap-values.yaml file that points at your private registry and internal artifact endpoint. Choose the tab that matches your database and observability configuration. Replace <account-id>, <region>, and the internal endpoint placeholders with your values.

image:
  registry: <account-id>.dkr.ecr.<region>.amazonaws.com
  repository: agentregistry-enterprise
  name: server
  tag: v2026.8.0
  pullPolicy: IfNotPresent

global:
  binaryHost: https://artifacts.internal.example.com
  binaryBucket: agentregistry-enterprise
  imagePullSecrets: []

binary:
  agentgateway:
    version: v2026.8.0
  agw-sync:
    version: v2026.8.0
  sts:
    version: v2026.8.0

oidc:
  issuer: https://idp.internal.example.com/realms/agentregistry
  clientId: ar-backend
  publicClientId: ar-ui
  roleClaim: groups
  superuserRole: admins

licensing:
  createSecret: false
  secretName: enterprise-agentregistry-license

database:
  postgres:
    type: external
    external:
      secretRef:
        name: agentregistry-postgres
        key: AGENT_REGISTRY_DATABASE_URL

clickhouse:
  enabled: true
  image:
    repository: <account-id>.dkr.ecr.<region>.amazonaws.com/agentregistry-enterprise/clickhouse-server
    tag: 26.2.5-alpine
  persistentVolume:
    enabled: true

telemetry:
  enabled: true
  collector:
    image:
      repository: <account-id>.dkr.ecr.<region>.amazonaws.com/agentregistry-enterprise/opentelemetry-collector-contrib
      tag: 0.148.0

image:
  registry: <account-id>.dkr.ecr.<region>.amazonaws.com
  repository: agentregistry-enterprise
  name: server
  tag: v2026.8.0
  pullPolicy: IfNotPresent

global:
  binaryHost: https://artifacts.internal.example.com
  binaryBucket: agentregistry-enterprise
  imagePullSecrets: []

binary:
  agentgateway:
    version: v2026.8.0
  agw-sync:
    version: v2026.8.0
  sts:
    version: v2026.8.0

oidc:
  issuer: https://idp.internal.example.com/realms/agentregistry
  clientId: ar-backend
  publicClientId: ar-ui
  roleClaim: groups
  superuserRole: admins

licensing:
  createSecret: false
  secretName: enterprise-agentregistry-license

database:
  postgres:
    type: bundled
    bundled:
      image:
        registry: <account-id>.dkr.ecr.<region>.amazonaws.com
        repository: agentregistry-enterprise
        name: postgres
        tag: "18"

clickhouse:
  enabled: true
  image:
    repository: <account-id>.dkr.ecr.<region>.amazonaws.com/agentregistry-enterprise/clickhouse-server
    tag: 26.2.5-alpine
  persistentVolume:
    enabled: true

telemetry:
  enabled: true
  collector:
    image:
      repository: <account-id>.dkr.ecr.<region>.amazonaws.com/agentregistry-enterprise/opentelemetry-collector-contrib
      tag: 0.148.0

image:
  registry: <account-id>.dkr.ecr.<region>.amazonaws.com
  repository: agentregistry-enterprise
  name: server
  tag: v2026.8.0
  pullPolicy: IfNotPresent

global:
  binaryHost: https://artifacts.internal.example.com
  binaryBucket: agentregistry-enterprise
  imagePullSecrets: []

binary:
  agentgateway:
    version: v2026.8.0
  agw-sync:
    version: v2026.8.0
  sts:
    version: v2026.8.0

oidc:
  issuer: https://idp.internal.example.com/realms/agentregistry
  clientId: ar-backend
  publicClientId: ar-ui
  roleClaim: groups
  superuserRole: admins

licensing:
  createSecret: false
  secretName: enterprise-agentregistry-license

database:
  postgres:
    type: external
    external:
      secretRef:
        name: agentregistry-postgres
        key: AGENT_REGISTRY_DATABASE_URL

clickhouse:
  enabled: false

telemetry:
  enabled: false

Step 7: Install

1. From the directory that contains the transferred chart package, install Solo Enterprise for agentregistry.

   helm upgrade --install agentregistry \
     ./offline-bundle/agentregistry-enterprise-2026.8.0.tgz \
     --namespace agentregistry-system \
     --values airgap-values.yaml \
     --wait \
     --timeout 10m

2. Verify that the Solo Enterprise for agentregistry pods are up and running.

   kubectl get pods -n agentregistry-system

   Example output:

   NAME                                                            READY   STATUS    RESTARTS   AGE
   agentregistry-enterprise-server-76f8fcc656-bmfsr                1/1     Running   0          2m21s
   agentregistry-enterprise-telemetry-collector-777798c5b4-d9cwt   1/1     Running   0          2m21s
   agentregistry-clickhouse-shard0-0                               1/1     Running   0          2m21s
   

Step 8: Validate

1. Confirm that the server pod pulls its image from your private registry and not from a public registry.

   kubectl -n agentregistry-system get pod \
     -l app.kubernetes.io/component=server \
     -o jsonpath='{range .items[*].spec.containers[*]}{.image}{"\n"}{end}'

2. Confirm that the binary URLs point at your internal artifact endpoint.

   kubectl -n agentregistry-system get configmap agentregistry-enterprise \
     -o jsonpath='{.data.AGENTGATEWAY_BIN_URL}{"\n"}{.data.AGW_SYNC_BIN_URL}{"\n"}{.data.STS_BIN_URL}{"\n"}'

Upgrade

For every upgrade, repeat the connected-staging and transfer phases for the new version:

1. On your connected workstation, set the new version and mirror the new server image and any changed dependency images. For more information, see Step 1 and Step 2.
2. Publish the matching runtime binaries to your internal artifact endpoint.
3. Pull the new Helm chart package and transfer it to the air-gapped environment.
4. Update the image tags and binary.*.version values in your airgap-values.yaml file.
5. Run the helm upgrade --install command with the new Helm chart package and values.

Keep the old images and binaries until the rollout is healthy and you no longer need to roll back. For general upgrade guidance, such as data migration considerations, see Upgrade.