How to Configure OpenHands Kubernetes Sandbox
You set up an openhands kubernetes sandbox by assigning a scoped Role in one namespace. Then you bind that Role to the agent service account for pod tasks. Teams often start by giving the agent broad cluster permissions to speed up testing. When roles are too wide, an agent can read or change workloads across the cluster. How the openhands kubernetes sandbox architecture works OpenHands runs coding tasks inside isolated containers so agent commands stay away from host machines. When you use K
Your coding agents run with your access.
Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.
You set up an openhands kubernetes sandbox by assigning a scoped Role in one namespace. Then you bind that Role to the agent service account for pod tasks. Teams often start by giving the agent broad cluster permissions to speed up testing. When roles are too wide, an agent can read or change workloads across the cluster.
How the openhands kubernetes sandbox architecture works
OpenHands runs coding tasks inside isolated containers so agent commands stay away from host machines. When you use Kubernetes as the runtime backend, the control plane starts a pod. Each agent session gets its own pod to run shell commands and edit code. Kubernetes RBAC controls what the OpenHands controller and the sandbox pod can do.
In Kubernetes RBAC, a Role holds rules that represent a set of permissions. These permissions are additive, which means there are no deny rules in the system. A Role always sets permissions inside one specific namespace. A ClusterRole is not namespaced and can cover cluster-scoped resources like nodes. It can also cover namespaced resources across all namespaces in the cluster.
To keep the sandbox isolated, you create a dedicated namespace for agent workloads. You define a Role in that namespace and attach it with a RoleBinding. A RoleBinding grants permissions inside one namespace and can reference a Role there. Avoid using a ClusterRoleBinding because that grants access across the entire cluster.
Scoping pod subresources for agent tasks
The OpenHands controller needs permission to create pods and run commands inside them. Kubernetes RBAC refers to resources by the exact name in the API URL. Some APIs use a subresource, such as a pod log or exec stream. In RBAC rules, you write the subresource with a slash after the resource name.
Your Role must allow the pod log subresource and the pod exec subresource. This lets the agent framework send commands into the sandbox and read the output. You should also check what service account runs inside the sandbox pod itself. If the agent does not call the Kubernetes API, give its pod no rules.
Teams sometimes try to lock down create rules to specific resource names. In Kubernetes RBAC, resource name limits on create apply only to top-level resources. You cannot restrict subresource creation to a single resource name in the same rule. Because of this, namespace separation remains the main boundary for agent sandbox pods.
Kubernetes RBAC + AI Sandbox Environments: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What native setup solves and where gaps remain
Native Kubernetes RBAC solves the problem of where an agent pod can run. A namespace Role and RoleBinding stop the controller from touching other team namespaces. They also prevent the agent from reading cluster-wide objects or changing node settings. This gives your platform team a clear boundary at the cluster API level.
Still, Kubernetes RBAC only checks who can call an API endpoint at login. It does not inspect what individual shell commands or database queries do in flight. Once the pod exec stream opens, Kubernetes allows every command inside that stream. If the sandbox pod holds database keys, the agent can run destructive queries.
Native roles also do not filter sensitive data returning through those database sessions. An agent query can pull emails, phone numbers, card numbers, or national IDs. Without runtime checks, raw results flow straight back into the agent model context. Teams need a way to inspect commands and rewrite matched fields in results.
Add request guardrails and response masking beside Kubernetes
Cluster roles and service accounts govern who reaches the Kubernetes API. Still, a broad role or agent can delete workloads or print sensitive values from ConfigMaps and logs. In practice, hoop.dev runs beside the API server as a sidecar for your Kubernetes API and checks every request and response alongside RBAC.
With hoop.dev Kubernetes controls, guardrails can allow listing Secret names while refusing reads of Secret data before execution. Data masking redacts matched keys in returned JSON responses and log streams in memory. Furthermore, hoop.dev holds SOC 2 Type II and is MIT licensed on GitHub.
Frequently asked questions
Should I use a Role or a ClusterRole for the agent sandbox?
Use a Role paired with a RoleBinding inside a dedicated sandbox namespace. This limits the agent controller to one namespace instead of the whole cluster.
How does OpenHands run commands inside the Kubernetes pod?
The controller uses the Kubernetes pod exec and pod log subresources through the API. You must include these subresources with a slash in your namespace Role rules.
Can Kubernetes RBAC block dangerous shell commands inside the sandbox?
No, Kubernetes RBAC only decides if a user or service can open the exec stream. It does not read or block specific shell commands or queries inside the session.
Related guides
In this post