--- title: "Artifacts Management and hsk8s (Hyperscience Kubernetes CLI)" slug: "artifacts-management-and-hsk8s-hyperscience-kubernetes-cli" updated: 2025-11-04T14:18:12Z published: 2025-11-04T14:18:12Z canonical: "help.hyperscience.ai/artifacts-management-and-hsk8s-hyperscience-kubernetes-cli" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.hyperscience.ai/llms.txt > Use this file to discover all available pages before exploring further. # Artifacts Management and hsk8s (Hyperscience Kubernetes CLI) ## Background The Hyperscience Platform is deployed using multiple container images. You can obtain these images from the public Hyperscience container registry and then either **copy all of them to your internal registry** or **set up your internal registry to cache them**. Hyperscience provides a utility called `hsk8s` to help with this process. While it's not required, it can automate the synchronization of images to your internal registry (the first option mentioned above). You should use the latest version of `hsk8s` if possible. Even if you choose to cache the images, `hsk8s` is still useful for other tasks like setting up Helm, generating support bundles, and copying other assets like machine learning models . To run the Hyperscience platform on Kubernetes, you'll also need to have **Helm** and **Kubectl** installed. ## Hyperscience Kubernetes CLI ### Installation #### Hyperscience token The following steps require a Hyperscience token to access the public Hyperscience artifacts. If you do not have one, contact your Hyperscience representative for assistance. Once you have it, export the `HS_TOKEN` environment variable with its value: ```bash export HS_TOKEN= ``` ```powershell $HS_TOKEN= ``` Make sure to replace `<your_token>` with the actual value. #### Supported OS / architecture combinations The following OS/architecture combinations are supported: - darwin-arm64 - darwin-amd64 - linux-arm - linux-amd64 - windows-arm64 - windows-amd64 #### Download the binary and install **Darwin and Linux** You can download the binary from our asset-hosting partner with the following URL scheme. Replace with the architecture where you are running it. ```bash export HS_K8S_CLIENT_ARCH=darwin-arm64 # ensure you use the appropriate arch from the list above for your own system export HS_K8S_CLIENT_VERSION=latest # Using your token in the url curl -OL "https://dl.cloudsmith.io/${HS_TOKEN}/hyperscience/prod/raw/names/hsk8s-${HS_K8S_CLIENT_ARCH}/versions/${HS_K8S_CLIENT_VERSION}/hsk8s-${HS_K8S_CLIENT_ARCH}-${HS_K8S_CLIENT_VERSION}.tgz" # Or using basic auth curl -OL -u token:${HS_TOKEN} "https://dl.cloudsmith.io/basic/hyperscience/prod/raw/names/hsk8s-${HS_K8S_CLIENT_ARCH}/versions/${HS_K8S_CLIENT_VERSION}/hsk8s-${HS_K8S_CLIENT_ARCH}-${HS_K8S_CLIENT_VERSION}.tgz" ``` After you've successfully downloaded the binary, you need to untar it, change its permissions, and move it to a directory in your `$PATH`: ```bash tar -xvf hsk8s-${HS_K8S_CLIENT_ARCH}-${HS_K8S_CLIENT_VERSION}.tgz chmod 744 hsk8s-${HS_K8S_CLIENT_ARCH} mv hsk8s-${HS_K8S_CLIENT_ARCH} /usr/local/bin/hsk8s ``` Test that you've installed the binary correctly with the following command: ```bash hsk8s version ``` **Windows** You can download the binary from our asset-hosting partner with the following URL scheme. Replace with the architecture where you are running it. ```powershell $HS_K8S_CLIENT_ARCH=windows-amd64 # ensure you use the appropriate arch from the list above for your own system $HS_K8S_CLIENT_VERSION="latest" $HSK8S_URL="https://dl.cloudsmith.io/${HS_TOKEN}/hyperscience/prod/raw/versions/${HS_K8S_CLIENT_VERSION}/hsk8s-${HS_K8S_CLIENT_ARCH}.exe" Invoke-WebRequest $HSK8S_URL -OutFile hsk8s.exe ``` Depending on your Windows setup, you may add the file directory to your system’s `PATH` variable to persist the config. Test that you've installed the binary correctly with the following command: ```powershell .\hsk8s.exe version ``` ### Usage #### Downloading container Images `hsk8s` can be used to copy container images from Hyperscience repositories to your own. The application uses the [Docker HTTP V2 Registry API](https://docs.docker.com/registry/spec/api/) to handle communication, so a local `docker` installation is **NOT required**. The application does require network access to our publicly-available repositories, as well as network access to your own internal container registry. You will need 4 **distinct** repositories with the following default names: - forms - sdm_blocks - trainer - hyperoperator These names can be overridden with the `hsk8s` parameters `--forms-repo`, `--blocks-repo`, `--trainer-repo`, and `--operator-repo`, respectively. #### Examples > [!WARNING] > **IMPORTANT:** All internal repositories must already exist before running the commands below. **Streaming Images to AWS ECR** This command will stream images from Hyperscience repositories to an ECR Registry of your choice. The user running this command will need to be logged in to [https://aws.amazon.com/cli/](https://aws.amazon.com/cli/) under a profile that has the following IAM permissions: - ecr:BatchGetImage - ecr:BatchCheckLayerAvailability - ecr:CompleteLayerUpload - ecr:GetDownloadUrlForLayer - ecr:InitiateLayerUpload - ecr:PutImage - ecr:UploadLayerPart To see all the options of the command, type: ```bash hsk8s image stream --help ``` Now you can run the command: ```bash hsk8s image stream 0123456789.dkr.ecr.us-east-1.amazonaws.com --token $HS_TOKEN --aws ``` **Note:** In the command above, replace `0123456789.dkr.ecr.us-east-1.amazonaws.com` with your ECR registry endpoint. Note that it doesn't contain the repository name. You can obtain the name through the AWS Console or CLI. Alternatively, if you cannot use `hsk8s` for image streaming, you can do it directly with `docker`. In that case, except for the above repositories, you will also need to stream a supporting image for the trainer database, as shown below. `hsk8s` does that automatically. ```bash docker pull docker.cloudsmith.io/hyperscience/prod/postgres:16.6-alpine docker tag docker.cloudsmith.io/hyperscience/prod/postgres:16.6-alpine 0123456789.dkr.ecr.us-east-1.amazonaws.com/trainer:postgres...16.6-alpine docker push 0123456789.dkr.ecr.us-east-1.amazonaws.com/trainer:postgres...16.6-alpine ``` **Streaming Images to Google Artifact Registry** To push to GCP's Artifact Registry, you must first configure its authentication as explained in Google's [Store Docker container images in Artifact Registry](https://cloud.google.com/artifact-registry/docs/docker/store-docker-container-images#auth). The user pushing the images will require the Artifact Registry Writer role (`roles/artifactregistry.writer`) (see Google’s [Artifact Registry Roles and Permissions](https://cloud.google.com/iam/docs/roles-permissions/artifactregistry#artifactregistry.writer)). Then, running the following command will push all images that Hyperscience needs to the `my-repo` repository. In contrast to other Docker registries, you will need to create only the top-level repository in GAR. The others will be created automatically when the first image is pushed. ```bash hsk8s image stream us-east4-docker.pkg.dev/my-project-id/my-repo --token $HS_TOKEN ``` **Streaming Only Forms to a Private Repository** Sample: ```bash hsk8s image stream your-docker-registry.net --token $HS_TOKEN --forms --forms-repo hyperscience-forms --basic username:password --forms-version 40.0.3 ``` This example demonstrates a few of the many options supported by the `hk8s image stream` subcommand: 1. To connect to a private docker repository that supports basic authentication, you can use the `--basic` flag like so: `--basic username:password`. 2. To stream only the main Hyperscience image (`forms`), you can use the `--forms` flag. Likewise, the command also supports streaming only `--blocks`, `--trainer` and `--operator`. These flags can be combined to stream different combinations of components. 3. To specify a target repository that's different from the default, you can use the `--forms-repo`, `--blocks-repo`, `--trainer-repo`, or `--operator-repo` flags. 4. To specify a specific application version to download (that is not `latest`), you can use `--forms-version` or `--operator-version`. Since the `block` versions must match the `forms` version, the `--forms-version` flag is used for all of those images. 5. To stream trainer of another version, you can issue a command like: `hsk8s image stream your-docker-registry.net  --trainer --forms-version  --token $HS_TOKEN`. Going back to the above command, this command will stream the `forms:40.0.3` image to `your-docker-registry.net/hyperscience-forms:40.0.3` using Basic Auth credentials. ## Installing `kubectl` For instructions on installing `kubectl`, see the Kubernetes documentation: - [Linux instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) - [MacOS instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/) - [Windows instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/) ### Example `kubectl` setup to access EKS This example assumes Bash shell is being used. It is trivial to translate it to PowerShell as needed for a Windows environment. Create a file named `hs_env.bash` with the following content: ```bash export HS_K8S_NAMESPACE=hyperscience-dev export HS_KUBECTL_CONTEXT=hyperscience-dev export HS_HELM_RELEASE=hyperscience-dev export HS_HELM_CHART=hyperscience/hyperscience ``` You can replace `hyperscience-dev` with any names you want, but leave `hyperscience/hyperscience` as it is. Import the environment from the newly created file: ```bash source hs_env.bash ``` Then, import the config for your EKS cluster: ```bash aws eks update-kubeconfig --region  --name  --alias $HS_KUBECTL_CONTEXT kubectl config use-context $HS_KUBECTL_CONTEXT kubectl config set-context $HS_KUBECTL_CONTEXT --namespace=$HS_K8S_NAMESPACE ``` Alternatively, follow the instructions in Google's [Install kubectl and configure cluster access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) for guidance on how to authenticate to a GKE cluster in the Google Cloud Platform. ## Set up the Helm repository > [!WARNING] > **IMPORTANT:** Setting up the repository requires a local installation of Helm, the package manager for Kubernetes. If you don't have the tool, you should follow Helm's [Installing Helm](https://helm.sh/docs/intro/install/) instructions first. After you install Helm, run: ```bash hsk8s helm add --token $HS_TOKEN ``` to add the Hyperscience Helm Repository to your local repository cache. Now you can run commands like `helm repo update`, which will fetch the latest version of the Hyperscience's package for Helm (called `chart` in Helm's language) from the remote repository. ### Without using `hsk8s` If you skip `hsk8s` installation, you may set the Helm repository by using this endpoint: ```shell HS_HELM_REPO_URL="https://dl.cloudsmith.io/basic/hyperscience/prod/helm/charts/" ``` The following example shows how to configure the Hyperscience Helm repo for your local system without `hsk8s`. You may also use your `HS_HELM_REPO_URL`, username, and `HS_TOKEN` to add the Hyperscience Helm repo to a local registry, just as you would for JFrog Artifactory or similar repositories. ```shell helm repo add hyperscience https://dl.cloudsmith.io/basic/hyperscience/prod/helm/charts/ --username token --password $HS_TOKEN ``` ## Container image caching If you decide to set container image caching on your container registry instead of syncing container images manually each time, you need to configure your registry and adjust the Helm chart with the proper container image prefixes. Set up your container-registry product with the necessary information to proxy and cache the image requests from the Kubernetes cluster: ```yaml Repo URL: docker.cloudsmith.io Username: hyperscience/prod Password: $HS_TOKEN ``` Then, update the `values.yaml` file with the following information (see [Helm Chart](/deployment/docs/helm-chart#create-a-valuesyaml-file) for information on `values.yaml`): ```yaml # The specific paths may be dependent on the particular contianer registry in use. # Image names should be similar to your-artifactory-url.net/your-repo-name/hyperscience/prod/forms:42.0.0 # In your values.yaml, you'll need to include the following, with repository values being something like this: app:  repository: "your-artifactory-url.net/your-repo-name/hyperscience/prod/forms" blocks:  repository: "your-artifactory-url.net/your-repo-name/hyperscience/prod/sdm_blocks" operator:  repository: "your-artifactory-url.net/your-repo-name/hyperscience/prod/hyperoperator" trainer:  repository: "your-artifactory-url.net/your-repo-name/hyperscience/prod/trainer"  db:    repository: "your-artifactory-url.net/your-repo-name/hyperscience/prod/postgres" ```