Skip to main content

Protect OpenShell sandboxes

Task

Discover the sandboxes of an OpenShell that you install and run yourself, let AIControls register each one in Audit mode, and switch it to Enforce, so it can call only the models and tools its Blueprint grants. Each agent runs in its own namespace.

Self-managed installations only

Workload Trust is available only in private, self-managed AIControls installations, on premises or in a cloud cluster that you run. It needs a dedicated cluster that you run, with Kyverno, Kyverno Runtime, and cluster OIDC and RBAC access in place. Nirmata-hosted (SaaS) workspaces don't include it. See Feature availability.

AIControls treats a sandbox like any other Kubernetes workload, and it adds no OpenShell-specific behavior beyond discovering the Sandbox kind. This page covers an OpenShell that you install and run yourself. The bundled OpenShell install is documented separately.

A sandbox registers automatically when it carries the opt-in label, runs in an allowed namespace, passes the readiness rules, and names a Blueprint that allows automatic registration. This page walks through that flow for an Agent Sandbox Sandbox resource that you create yourself, because the OpenShell Kubernetes driver rejects the projected ServiceAccount token that the flow uses in the sandboxes it creates.

Before you begin​

  • You need an administrator session, and AIControls must run in the cluster that runs OpenShell. See Workload discovery.
  • The cluster needs the Agent Sandbox controller and its Sandbox custom resource definition (CRD). AIControls scans the Sandbox kind automatically when the CRD exists.
  • An upstream model and an MCP server that the sandbox needs are configured. See Connect an MCP server.
  • To switch a sandbox to Enforce, your license must include workload enforcement: the Enterprise plan, or the Workloads add-on on the Business plan. See License management.
  • Kyverno is installed, so readiness rule R4 can read its policy reports. See Review Kubernetes posture.
  • Runtime controls are enabled, so readiness rule R6 can read sensor health. See Enable runtime controls.
  • Your cluster enforces Kubernetes NetworkPolicy, so the namespace can deny egress except to DNS and AIControls.

Give each agent its own namespace​

A sandbox authenticates with the ServiceAccount of its Pod, like every other workload, and AIControls allows one identity per workload. Sandboxes in one OpenShell workspace often run under the same sandbox ServiceAccount. Two sandboxes that share a ServiceAccount fail readiness rule R7, so the second one never registers.

To keep each sandbox's identity unique, create one OpenShell workspace for each agent:

  • In managed mode, OpenShell creates one namespace for each workspace, so one workspace per agent gives each agent its own namespace.
  • In operator mode, you create the namespace for each workspace yourself, and you install the upstream openshell-workspace chart in it. Without the chart, the first sandbox fails because the namespace has no ServiceAccount or Role.

A second sandbox of the same agent in that namespace shares the ServiceAccount and stays unregistered. See Bind a workload identity.

Allow automatic registration​

Do this once, as an administrator.

  1. Create or choose a Blueprint whose Access Binding grants the models and tools the agent needs, and turn on Allow automatic registration. Open Inventory → Workloads, select Blueprints, and select Edit. See Edit a Workload Blueprint.

  2. Open Setup → Settings → Workloads, find Automatic registration, and turn on Register ready workloads automatically.

  3. In Allowed namespaces, add the namespace of each agent. Names are exact. Select Save. See Register workloads automatically.

Opt a sandbox in​

Add the opt-in label, and optionally the Blueprint annotation, to the Sandbox resource. Put them on the Sandbox, not on its Pod template. OpenShell sets the openshell.ai/managed-by: openshell label on the sandboxes it creates, and AIControls uses it to show the OpenShell sandbox type.

apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
  name: research-1
  namespace: agent-research
  labels:
    openshell.ai/managed-by: openshell
    aicontrols.nirmata.io/auto-register: "true"
  annotations:
    aicontrols.nirmata.io/blueprint: research-agents

This example covers only an Agent Sandbox Sandbox that you create yourself. The OpenShell Kubernetes driver rejects a projected ServiceAccount token in the Pod of a sandbox it creates, so OpenShell-created sandboxes can't use this token path. The Pod of the sandbox in this example needs an audience-bound projected ServiceAccount token. Mount one in the Pod template, with the audience that matches identity.clusterOIDCAudience in your Helm values (set that value to aicontrols for this example), and have the agent send it as a bearer token to the AIControls gateway.

spec:
  podTemplate:
    spec:
      containers:
        - name: agent
          volumeMounts:
            - name: aicontrols-token
              mountPath: /var/run/secrets/aicontrols
              readOnly: true
      volumes:
        - name: aicontrols-token
          projected:
            sources:
              - serviceAccountToken:
                  path: token
                  expirationSeconds: 3600
                  audience: aicontrols

Also create a NetworkPolicy in the namespace that denies egress except to DNS and the AIControls gateway. Readiness rule R3 checks it. See Make a workload ready to register.

Discover the sandbox​

  1. Open Inventory → Workloads. The sandbox appears with the kind Sandbox and the OpenShell sandbox type within one discovery scan. Select Rescan to refresh it sooner.

  2. Let the agent make a call. A new installation locks down unregistered workloads, so the gateway blocks the call with workload_not_registered. The audit log attributes the call to the sandbox, for example agent-research/Sandbox/research-1.

Register the sandbox​

AIControls registers the sandbox on its next pass, about one minute after it reads Ready to register. The sandbox becomes Ready after it makes gateway calls that AIControls observes. Select the sandbox in Inventory → Workloads. The drawer shows Auto-registered when AIControls registers it in Audit mode with the Blueprint's access.

In Audit mode, the gateway allows the sandbox's calls and records which calls Enforce would block. If the sandbox stays unregistered, the drawer names the readiness rules that fail. See Fix a refusal.

Switch the sandbox to Enforce​

  1. Open the sandbox's detail page and select the AI access tab.
  2. Select Enforce on the Mode card, review the preview, and select Switch to Enforce. See Switch a workload to Enforce.

From its next call, the sandbox can use only the models and tools its Blueprint grants. A call outside the grant is denied by the access default, and the audit log records the reason, for example accessdefault:llm:workload for a model and accessdefault:mcp:workload for a tool. A denied call never reaches the model provider or the MCP server.

Check that a second sandbox stays unregistered​

warning

Run this check only in a namespace where you can interrupt a registered agent. AIControls can also withdraw the registration of the first sandbox about a minute after the second one appears, which stops the first sandbox's calls. This is a known problem.

Create another sandbox with the opt-in label in the same namespace. It shares the ServiceAccount, so it fails readiness rule R7: the drawer shows Auto-registration refused with a message that names R7, and AIControls doesn't register it. To register it, move it to its own namespace.

Limits​

  • AIControls evaluates the same readiness rules for a sandbox as for any other workload, including rule R5. No rule is skipped for sandboxes.
  • A label doesn't prove that OpenShell manages a sandbox, because any workload author can set it.
Last updated on