OpenShell has added a Kubernetes integration that replaces its previous scheduler with the Agent Sandbox resource (agents.x-k8s.io). The gateway creates the sandbox objects, and the Agent Sandbox controller turns each sandbox into a workload Pod, a supervisor Pod, and the associated Kubernetes resources. This change lets platform engineers manage AI agents with the same declarative tools they already use for workloads.
Key Architectural Shifts
- Gateway‑driven sandbox creation: Sandboxes are instantiated by calling the OpenShell gateway over mTLS; the Kubernetes API is not used for creation yet.
- Agent Sandbox CRD: The sandbox appears as a custom resource that, when reconciled, produces a workload Pod (the agent), a supervisor Pod, a Service, a PVC for
/sandbox, and two NetworkPolicies. - Supervisor mediation: The workload Pod has no direct outbound network. All traffic is funneled through the supervisor, which performs per‑request policy checks before opening upstream connections.
- Policy as source of truth: The gateway records the sandbox definition and enforces filesystem, process, network and credential rules before the agent starts.
Implementation Details Practitioners Need to Know
Deploy the Cilium CNI (or another that enforces both ingress and egress) and replace the default kindnet in the demo. Install the Agent Sandbox controller and its CRDs, then deploy the OpenShell gateway via its Helm chart. Creating a sandbox uses a CLI command such as:
openshell sandbox create --workspace demo --name policy-demo --from nicolaka/netshoot@sha256:… --no-auto-providers
The command sends a request to the gateway, which authenticates the caller, resolves the container image, validates the declared policy, and stores a sandbox record. The driver then creates two NetworkPolicies: one that blocks all outbound traffic for the workload Pod and permits inbound traffic only from the supervisor on TCP 5500, and another that allows the supervisor to reach the workload.
Before the workload Pod is scheduled, a scheduling gate holds it while the driver validates the pod spec: non‑root UID/GID, no extra capabilities, RuntimeDefault seccomp, no host namespaces, no ServiceAccount token, and required labels and volumes. If any admission webhook mutates these fields, creation fails.
After the pod passes validation, the supervisor Pod is created, a Service exposing the workload’s port 5500 is provisioned, and TLS/bootstrap secrets are generated. The supervisor authenticates to the gateway using a composite identity (namespace, sandbox UID, pod UID, runtime generation) and receives the policy payload.
Operational and Security Implications
- Fine‑grained runtime controls: Filesystem access is limited via Landlock, process capabilities are dropped, seccomp profiles are enforced, and outbound network is filtered per binary, host, port and HTTP method.
- Credential handling: Agents see placeholder values; the supervisor injects real API keys only for allowed endpoints, reducing exposure of secrets.
- Dynamic policy updates: Policies can be refreshed without restarting the sandbox; the supervisor loads the new version and waits for confirmation from the runtime.
- Scalability consideration: Each agent currently requires a dedicated supervisor Pod, which may limit scale in large environments.
- Lifecycle management: Stopping a sandbox suspends the custom resource and deletes the workload Pod while preserving the PVC. Starting creates a new runtime generation, re‑running all pod checks. Deleting the sandbox cleans up all owned resources via owner references.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
Platform teams can now treat AI agents as first‑class Kubernetes workloads, leveraging existing CI/CD pipelines, policy-as-code tools, and observability stacks. The sandbox model forces explicit declaration of filesystem, process and network boundaries, which simplifies audit and compliance. Teams should evaluate the supervisor‑per‑agent overhead against their scale requirements and consider contributing to the open issue for a native OpenShellSandbox CRD if tighter integration is needed. Finally, ensure the cluster’s CNI enforces both ingress and egress policies, as the sandbox’s security guarantees depend on those NetworkPolicies.