---
title: Getting started
weight: 10
aliases: /secure-agent-workspace/getting-started/
---

:toc:
:imagesdir: /images
:_content-type: ASSEMBLY
include::modules/comm-attributes.adoc[]

[id="deploying-secure-agent-workspace-pattern"]
== Deploying the Secure Agent Workspace pattern

.Prerequisites

* An {ocp} cluster with *bare-metal worker nodes* to provide hardware virtualization to run a separate {VirtProductName} VM for each workspace. {VirtProductName} does not support nested virtualization.
** *For on-premises deployments*, install {ocp} 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 link:cluster-sizing[Cluster sizing] for advice on the size and number of nodes required.
** You can create an {ocp} cluster by using the link:https://console.redhat.com/openshift/create[Red{nbsp}Hat Hybrid Cloud Console].
* A default storage class that can provision `ReadWriteOnce` volumes for the VM disks.
* Cluster administrator access. End users need no {ocp} 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 link:ideas-for-customization[Ideas for customization].
* The `oc` CLI. For instructions, see link:https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI].
* The Helm binary. For instructions, see link:https://helm.sh/docs/intro/install/[Installing Helm].
* The `openshell` CLI, version 0.1.x, from the link:https://github.com/NVIDIA/OpenShell/releases[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 link:https://validatedpatterns.io/learn/quickstart/[Patterns quick start].

[id="preparing-for-deployment-saw"]
== Preparing for deployment
.Procedure

. Fork the link:https://github.com/validatedpatterns-sandbox/secure-agent-workspace[secure-agent-workspace] repository on GitHub. You must fork the repository to add users and to customize this pattern.

. Clone the forked copy of this repository.
+
[source,terminal,subs="+quotes"]
----
$ git clone git@github.com:__<your-username>__/secure-agent-workspace.git
----

. Go to the root directory of your Git repository:
+
[source,terminal]
----
$ cd secure-agent-workspace
----

. Run the following command to set the upstream repository:
+
[source,terminal]
----
$ git remote add -f upstream git@github.com:validatedpatterns-sandbox/secure-agent-workspace.git
----

. Generate the SSH key pair that the pattern uses to reach the workspace VMs for troubleshooting:
+
[source,terminal]
----
$ make generate-keys
----
+
The keys are written to `~/.generated-ssh-keys/`.

. Save your API keys in files outside the repository, one key per line:
+
[source,terminal]
----
$ 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
----

. Make a local copy of the secrets template outside your repository to hold credentials for the pattern.
+
[WARNING]
====
Do not add, commit, or push this file to your repository. Doing so might expose personal credentials to GitHub.
====
+
Run the following command:
+
[source,terminal]
----
$ 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.

. 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:
+
[source,yaml]
----
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.

. Optional: To customize the deployment, create and switch to a new branch by running the following command:
+
[source,terminal]
----
$ git checkout -b my-branch
----
+
Make your changes, then stage, commit, and push them:
+
[source,terminal]
----
$ 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 {rh-gitops} syncs from it.

[id="deploying-cluster-using-patternsh-file-saw"]
== Deploying the pattern by using the pattern.sh file

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

. Log in to your cluster.

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

.. Log in to the cluster by running the following command:
+
[source,terminal]
----
$ oc login --token=<retrieved-token> --server=https://api.<your_cluster>.<domain>:6443
----
+
Or log in by running the following command:
+
[source,terminal]
----
$ export KUBECONFIG=~/<path_to_kubeconfig>
----

. Copy the prebuilt template VM image into the cluster's internal registry. This takes about 5 minutes:
+
[source,terminal]
----
$ make copy-images
----

. Deploy the pattern to your cluster. Run the following command:
+
[source,terminal]
----
$ ./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:
+
[source,terminal]
----
$ export TARGET_BRANCH=my-branch
$ export TARGET_ORIGIN=origin
$ ./pattern.sh make install
----

.Verification

. Check the health of the Argo CD applications:
+
[source,terminal]
----
$ ./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.

. Verify that the Operators are installed. In the {ocp} web console, go to *Operators \-> Installed Operators* and confirm that the following Operators are present:
+
* {VirtProductName}
* Red{nbsp}Hat build of Keycloak
* {eso}

. Verify that each user's VM is running. For the user `alice`:
+
[source,terminal]
----
$ oc get vm -n saw-alice
----
+
.Example output
+
[source,terminal]
----
NAME    AGE   STATUS    READY
alice   12m   Running   True
----

. Check that the installer in the VM finished. Both steps must show `"phase": "Done"`:
+
[source,terminal]
----
$ make openshell-saw-status OPENSHELL_SAW_NAME=alice
----
+
To follow the installer as it runs, use `make openshell-saw-logs OPENSHELL_SAW_NAME=alice`.

[id="accessing-a-workspace-saw"]
== Accessing a workspace

. 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`.
+
[source,terminal]
----
$ export OPENSHELL_SAW_NAME=alice
$ make openshell-saw-configure-gateway
$ openshell gateway login alice
----

. List the sandboxes of the default profile:
+
[source,terminal]
----
$ openshell sandbox list
$ openshell sandbox list --workspace cuda-dev
----
+
.Example output
+
[source,terminal]
----
NAME      CREATED              PHASE
notebook  2026-09-30 14:40:42  Ready
----

. Open the OpenClaw agent in the `notebook` sandbox, in the terminal or in the browser:
+
[source,terminal]
----
$ 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`.

. Open the OpenShell web UI, which lists the user's workspaces and sandboxes:
+
[source,terminal]
----
$ oc get route alice-webui -n saw-alice -o jsonpath='https://{.spec.host}{"\n"}'
----

. 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:
+
[source,text]
----
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:
+
[source,terminal]
----
$ openshell --gateway alice --workspace default \
  logs notebook --since 5m --source sandbox
----

[id="next-steps-getting-started-saw"]
== Next steps

* link:ideas-for-customization[Ideas for customization]
* link:cluster-sizing[Cluster sizing]
* link:troubleshooting[Troubleshooting]