OpenShell has moved from a standalone runtime to a Kubernetes‑native sandbox that is provisioned through the Agent Sandbox controller. The change means platform engineers can manage AI agents with the same objects—Pods, Services, PVCs, Secrets, and NetworkPolicies—they already use, while retaining fine‑grained runtime controls.
Control Model and Policy Definition
All permissions are expressed in a YAML manifest that the OpenShell gateway validates before a sandbox is created. Four control domains are supported:
- Filesystem: Landlock rules restrict read‑only paths (e.g.,
/usr,/etc) and designate writable locations such as/sandbox,/tmp, and/dev/null. - Process: The runtime drops the agent to a non‑root UID/GID, removes capabilities, and applies a
RuntimeDefaultseccomp profile. - Network: Outbound traffic is blocked by default. Policies can allow traffic per binary, host, port, and HTTP method, and they are enforced by the supervisor rather than by Kubernetes alone.
- Credentials: Agents see placeholder values for API keys; the supervisor injects the real secret only for endpoints that the policy permits.
Kubernetes Integration and Lifecycle
The OpenShell gateway owns each sandbox and talks to the Agent Sandbox controller, which materialises the sandbox as a set of standard Kubernetes resources. The flow is:
- Client calls
openshell sandbox create …over mTLS; the request never touches the Kubernetes API directly. - The gateway authenticates the caller, resolves the container image, validates the policy, and records a sandbox object in a “Provisioning” phase.
- Two NetworkPolicies are created: one that isolates the workload pod (no egress, inbound only from the supervisor on TCP 5500) and another that permits the supervisor pod to communicate outward.
- A
Sandboxcustom resource is created in a suspended state. The controller then creates the workload pod, a PVC for/sandbox, and a scheduling gate that holds the pod until the gateway’s checks pass. - After the pod passes admission checks (non‑root UID, no extra capabilities, correct labels, etc.), a supervisor pod and a Service exposing port 5500 are provisioned. The supervisor authenticates to the gateway using a token tied to the namespace, sandbox UID, and pod UID.
- The supervisor opens a single outbound connection to the workload; every agent request—HTTP, exec, SSH, file sync—flows through this tunnel where policy is re‑checked.
Policy updates are applied by loading a new version into the running sandbox; the agent does not need to restart. Stopping a sandbox suspends the custom resource and deletes the workload pod while preserving the PVC. Starting recreates the pod with a fresh runtime generation.
Operational and Security Implications
Because each agent runs behind a dedicated supervisor, isolation is strong but the one‑supervisor‑per‑agent model may limit scalability in large clusters. The architecture relies on a CNI that enforces both ingress and egress NetworkPolicies; the demo swaps Kindnet for Cilium to satisfy this requirement. Kyverno admission webhooks validate the generated Kubernetes objects before they are persisted, adding a second line of defense.
NetworkPolicy alone cannot express “binary X may read but not create” rules; OpenShell fills that gap by inspecting the calling binary and HTTP method at runtime. This capability enables dynamic tightening of outbound permissions without redeploying pods.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
- Adopt the OpenShell gateway Helm chart and the Agent Sandbox controller to treat AI agents as first‑class Kubernetes workloads.
- Ensure your cluster runs a CNI that supports both ingress and egress policies (e.g., Cilium) before enabling OpenShell.
- Plan for the supervisor‑per‑agent overhead; evaluate whether the security benefits outweigh the additional pod count in your environment.
- Leverage Kyverno or similar admission controllers to enforce the required pod security standards automatically.
- Use the policy‑update workflow to adjust outbound permissions on‑the‑fly, reducing the need for pod restarts during incident response.
