Validated Patterns

Deploying the Secure Agent Workspace pattern

Prerequisites

  • An OpenShift Container Platform cluster with bare-metal worker nodes to provide hardware virtualization to run a separate OpenShift Virtualization VM for each workspace. OpenShift Virtualization does not support nested virtualization.

    • For on-premises deployments, install OpenShift Container Platform on bare-metal servers with Intel VT-x or AMD-V enabled in the firmware.

    • For public cloud deployments, select bare-metal instance types for workers, for example, on AWS, select m5.metal or c5n.metal.

    • See Cluster sizing for advice on the size and number of nodes required.

    • You can create an OpenShift Container Platform cluster by using the Red Hat Hybrid Cloud Console.

  • A default storage class that can provision ReadWriteOnce volumes for the VM disks.

  • Cluster administrator access. End users need no OpenShift Container Platform access: they sign in to the workspaces with Keycloak.

  • An API key for each service that the default profile uses: build.nvidia.com (NVIDIA Nemotron) and Brave Search. To use a model server of your own instead, see Ideas for customization.

  • The oc CLI. For instructions, see Getting started with the OpenShift CLI.

  • The Helm binary. For instructions, see Installing Helm.

  • The openshell CLI, version 0.1.x, from the OpenShell releases. A 0.0.x CLI cannot connect to the 0.1.x gateway that this pattern installs.

  • Additional installation tool dependencies. For details, see Patterns quick start.

Preparing for deployment

Procedure

  1. Fork the secure-agent-workspace repository on GitHub. You must fork the repository to add users and to customize this pattern.

  2. Clone the forked copy of this repository.

    $ git clone git@github.com:<your-username>/secure-agent-workspace.git

  3. Go to the root directory of your Git repository:

    $ cd secure-agent-workspace

  4. Run the following command to set the upstream repository:

    $ git remote add -f upstream git@github.com:validatedpatterns-sandbox/secure-agent-workspace.git

  5. Generate the SSH key pair that the pattern uses to reach the workspace VMs for troubleshooting:

    $ make generate-keys

    The keys are written to ~/.generated-ssh-keys/.

  6. Save your API keys in files outside the repository, one key per line:

    $ echo '<build.nvidia.com API key>' > ~/.nvidia-api-key
$ echo '<Brave Search API key>' > ~/.brave-api-key
$ chmod 600 ~/.nvidia-api-key ~/.brave-api-key

  7. Make a local copy of the secrets template outside your repository to hold credentials for the pattern.

    Do not add, commit, or push this file to your repository. Doing so might expose personal credentials to GitHub.

    Run the following command:

    $ cp values-secret.yaml.template ~/values-secret-secure-agent-workspace.yaml

    The template reads the SSH keys and the two API key files from the paths above. Edit your copy of the secrets file to store your API key files in a different location, or to use a different model provider.

  8. Optional: Choose who gets a workspace. Edit overrides/saw-users.yaml. Each entry in the users list defines one user. The name of each user is also used for that user’s namespace and for their VM:

    users:
  - name: alice
    profiles:
      - data-science

    The name must also be a user in Keycloak. The pattern’s realm includes the test users alice and bob. Each name must be a lowercase DNS label no more than 19 characters long.

  9. Optional: To customize the deployment, create and switch to a new branch by running the following command:

    $ git checkout -b my-branch

    Make your changes, then stage, commit, and push them:

    $ git add <changed-files>
$ git commit -m "Customize deployment"
$ git push origin my-branch

    The branch that you deploy must exist on your fork, because Red Hat OpenShift GitOps syncs from it.

Deploying the pattern by using the pattern.sh file

To deploy the pattern by using the pattern.sh file, complete the following steps:

  1. Log in to your cluster.

    1. Obtain an API token by visiting https://oauth-openshift.apps.<your_cluster>.<domain>/oauth/token/request.

    2. Log in to the cluster by running the following command:

      $ oc login --token=<retrieved-token> --server=https://api.<your_cluster>.<domain>:6443

      Or log in by running the following command:

      $ export KUBECONFIG=~/<path_to_kubeconfig>

  2. Copy the prebuilt template VM image into the cluster’s internal registry. This takes about 5 minutes:

    $ make copy-images

  3. Deploy the pattern to your cluster. Run the following command:

    $ ./pattern.sh make install

    To deploy a branch other than the one that is checked out, export TARGET_BRANCH before you run the command, and TARGET_ORIGIN if the branch is on a remote other than origin. For example:

    $ export TARGET_BRANCH=my-branch
$ export TARGET_ORIGIN=origin
$ ./pattern.sh make install
Verification

  1. Check the health of the Argo CD applications:

    $ ./pattern.sh make argo-healthcheck

    It might take 20 to 30 minutes for all applications to synchronize, the Operators to install, and the first workspace VM to boot.

  2. Verify that the Operators are installed. In the OpenShift Container Platform web console, go to Operators -> Installed Operators and confirm that the following Operators are present:

    • OpenShift Virtualization

    • Red Hat build of Keycloak

    • External Secrets Operator

  3. Verify that each user’s VM is running. For the user alice:

    $ oc get vm -n saw-alice
    Example output
    NAME    AGE   STATUS    READY
alice   12m   Running   True

  4. Check that the installer in the VM finished. Both steps must show "phase": "Done":

    $ make openshell-saw-status OPENSHELL_SAW_NAME=alice

    To follow the installer as it runs, use make openshell-saw-logs OPENSHELL_SAW_NAME=alice.

Accessing a workspace

  1. Register the user’s gateway and log in.

    Run the following commands, then use the browser window that opens to log in using Keycloak. The test user is alice with password alice.

    $ export OPENSHELL_SAW_NAME=alice
$ make openshell-saw-configure-gateway
$ openshell gateway login alice

  2. List the sandboxes of the default profile:

    $ openshell sandbox list
$ openshell sandbox list --workspace cuda-dev
    Example output
    NAME      CREATED              PHASE
notebook  2026-09-30 14:40:42  Ready

  3. Open the OpenClaw agent in the notebook sandbox, in the terminal or in the browser:

    $ make openclaw-tui SANDBOX_NAME=notebook
$ make openclaw-gui SANDBOX_NAME=notebook GUI_PORT=28789

    The browser UI opens through an SSH tunnel on http://localhost:28789.

  4. Open the OpenShell web UI, which lists the user’s workspaces and sandboxes:

    $ oc get route alice-webui -n saw-alice -o jsonpath='https://{.spec.host}{"\n"}'

  5. Optional: See the sandbox policy in effect. GitHub is not one of the hosts that the default profile allows, so the sandbox’s egress proxy blocks the agent’s request. In the OpenClaw agent of the notebook sandbox, enter the following prompt:

    Use your terminal tool to run curl -sS --max-time 10 https://api.github.com/zen. Show the command and its exact output.

    The command fails because the connection is denied. To see the denial, view the sandbox logs:

    $ openshell --gateway alice --workspace default \
  logs notebook --since 5m --source sandbox

Next steps

Edit this page Open a documentation issue

QUICKLINKS

CONTRIBUTE

STAY IN TOUCH

Validated Patterns

Validated Patterns are an evolution of how you deploy applications in a hybrid cloud. With a pattern, you can automatically deploy a full application stack through a GitOps-based framework. With this framework, you can create business-centric solutions while maintaining a level of Continuous Integration (CI) over your application.