Install the Arena builder

Enterprise

Install the Arena builder agent into a workspace namespace with the omnia-arena-builder Helm chart.

The builder is a hidden, dashboard-only agent. It agrees a brief with you in the dashboard, then writes and validates a PromptArena project inside a sandbox bound to that project. For the objects the chart renders and every value, see omnia-arena-builder chart.

Prerequisites

Omnia 0.9.0 or later with Enterprise enabled. Arena is an Enterprise feature.
A workspace namespace whose Workspace enables storage (spec.storage). The sandbox mounts the project from the PVC workspace-<namespace>-content, which Omnia creates on first use. With storage disabled every sandbox claim fails with NoWorkspaceStorage. See Workspace.
A Provider in that namespace for the builder to run on.
Nodes that can pull ghcr.io/altairalabs/omnia-promptarena-sandbox.

Install the builder

List the Providers in the workspace namespace and pick one:
Terminal window
```
kubectl get providers -n ws-demo
```
Install the chart at the same version as your Omnia release, into the workspace namespace, naming the Provider:
Terminal window
```
helm install arena-builder oci://ghcr.io/altairalabs/charts/omnia-arena-builder \
  --version <omnia-version> \
  --namespace ws-demo \
  --set provider.name=claude
```
provider.name has no default, and the install fails schema validation without it. The published chart pins the release’s sandbox image by digest. To run a different image, set sandbox.image.digest and, for a mirror, sandbox.image.repository.
If the Workspace sets spec.runtime.serviceAccountName, give the builder its own ServiceAccount. A Workspace that sets it runs every agent in the namespace as one ServiceAccount, the usual wiring for AKS Workload Identity, EKS IRSA and GKE Workload Identity. Omnia identifies an agent by its ServiceAccount, so agents that share one cannot be told apart. The builder needs no cloud identity when its Provider uses an API key, and the operator always creates <agent.name>-facade:
Terminal window
```
helm upgrade arena-builder oci://ghcr.io/altairalabs/charts/omnia-arena-builder \
  --version <omnia-version> --namespace ws-demo --reuse-values \
  --set agent.serviceAccountName=arena-builder-facade
```
Setting it also opts the builder out of the Workspace’s pod labels. See runtime for the sharing rules.
If you install the chart under another agent.name, set dashboard.builder.agent in the omnia chart to match, or set spec.builder on the Workspace. The dashboard finds the builder by name. To declare the project on another mount role, see Helm values: Arena builder and Workspace spec.builder.

Verify

List the builder’s objects:

kubectl get sandboxclass,toolregistry,promptpack,agentruntime,toolpolicy \
  -n ws-demo -l omnia.altairalabs.ai/role=arena-builder

The AgentRuntime reaches phase Running once one of its pods is ready:

kubectl get agentruntime arena-builder -n ws-demo

No sandbox pod runs at install. The operator creates a SandboxClaim when a builder session opens, and the sandbox starts for that claim. The claim’s project mount uses the project mount role, which the omnia chart configures by default in operator.sandboxAPI.mountRoles.

To use the builder, see Generate a project with the builder.

Troubleshooting

AgentRuntime in phase Failed with ProviderNotFound

ProviderReady is False with reason ProviderNotFound. provider.name names no Provider in the namespace. Upgrade the release with the right name.

Tool calls refused with deniedBy=no-matching-permit

No ToolPolicy selects the builder’s registry. Leave toolPolicy.enabled at true, or create a ToolPolicy that selects the registry named agent.name.

SandboxClaim Ready=False with reason NoWorkspaceStorage

The namespace’s Workspace has storage disabled, no Workspace owns the namespace, or the operator provisions no PVC. The dashboard shows “This workspace has no content storage”.

SandboxClaim Pending with reason WaitingForStorage for more than a moment

The operator created workspace-<namespace>-content and it has not appeared. Check the PVC and its StorageClass.

SandboxClaim Ready=False with reason MountNotGranted

The claim mounts the project but nothing proves the operator wrote it: something else created it, or it predates the admission policy. Start a new builder session.

The dashboard shows “Could not open the builder’s sandbox” with ClaimPolicyNotInForce

The omnia chart’s <fullname>-sandbox-claim-<hash> ValidatingAdmissionPolicy is missing (Kubernetes older than 1.30) or was edited in place. The operator creates no project claim without it. After an edit, delete the policy and upgrade the omnia chart.

The dashboard shows “Could not open the builder’s sandbox” with ClaimPolicySettling

The admission policy was created moments ago. The operator waits out operator.sandboxAPI.claimPolicyGrace before it creates the sandbox. Try again after the time the message names.

The dashboard shows “Could not open the builder’s sandbox” with UnknownMountRole or InvalidMountRole

UnknownMountRole: neither operator.sandboxAPI.mountRoles nor the Workspace’s spec.sandboxMountRoles configures the builder’s mount role (dashboard.builder.mountRole or the Workspace’s spec.builder.mountRole).

InvalidMountRole: the Workspace’s spec.sandboxMountRoles entry for that role has an invalid path, or one that overlaps another role’s.

The dashboard shows “You cannot start a builder sandbox here”

The session’s project mount was refused with MountNotAuthorized. You need the mount role’s minRole in the workspace, editor by default.

If the message says “this request’s user was not verified by the operator”, the builder’s facade could not exchange your sign-in for a verified token. Look for subject exchange failed in the builder facade’s log.

omnia-arena-builder chart: rendered objects, values and the sandbox image
Generate a project with the builder
SandboxClaim: mount roles, who may write a mounting claim, and the SandboxClass fields
Codegen sandbox isolation
Configure tool policies