OpenShellOpenShell enforces sandbox security across four layers: network, filesystem, process, and inference. This page documents every configurable control, its default, what it protects, and the risk of relaxing it.
For the full policy YAML schema, refer to the Policy Schema. For the architecture of each enforcement layer, refer to How OpenShell Works.
If you use NemoClaw to run OpenClaw assistants, its Security Best Practices guide covers additional entrypoint-level controls, policy presets, provider trust tiers, and posture profiles specific to the NemoClaw blueprint.
OpenShell applies security controls at two enforcement points.
OpenShell locks static controls at sandbox creation and requires destroying and recreating the sandbox to change them.
You can update dynamic controls on a running sandbox with openshell policy update or openshell policy set.
The CONNECT proxy and OPA policy engine enforce all network controls at the gateway level.
Every outbound connection from the sandbox goes through the CONNECT proxy.
The proxy evaluates each connection against the OPA policy engine.
If no network_policies entry matches the destination host, port, and calling binary, the proxy denies the connection.
The sandbox runs in a dedicated Linux network namespace with a veth pair.
All traffic routes through the host-side veth IP (10.200.0.1) where the proxy listens.
Even if a process ignores proxy environment variables, it can only reach the proxy.
Kubernetes user namespaces (hostUsers: false) map container UID 0 to an unprivileged host UID.
Capabilities like CAP_SYS_ADMIN become namespaced. They grant power over container-local resources only, not the host.
This provides defense-in-depth: even if a container escape vulnerability exists, the attacker lands as an unprivileged host user.
The proxy identifies which binary initiated each connection by reading /proc/<pid>/exe (the kernel-trusted executable path).
It walks the process tree for ancestor binaries and parses /proc/<pid>/cmdline for script interpreters.
The proxy SHA256-hashes each binary on first use (trust-on-first-use). If someone replaces a binary mid-session, the hash mismatch triggers an immediate deny.
The protocol field on an endpoint controls whether the proxy inspects individual HTTP requests inside the tunnel.
audit vs enforce)When L7 inspection is active, the enforcement field controls whether the proxy blocks or logs rule violations.
The proxy auto-detects TLS on every tunnel by peeking the first bytes. When a TLS ClientHello is detected, the proxy terminates TLS transparently using a per-sandbox ephemeral CA. This enables credential injection and L7 inspection without explicit configuration.
After OPA policy allows a connection, the proxy resolves DNS and rejects connections where the resolved IP is internal (loopback, link-local, or RFC 1918 private).
When the agent requests an endpoint not in the policy, OpenShell blocks it and surfaces the request in the TUI for operator review. The system merges approved endpoints into the sandbox’s policy as a new durable revision.
Landlock LSM restricts which paths the sandbox process can read or write at the kernel level.
Landlock enforces filesystem access at the kernel level.
Paths listed in read_only receive read-only access.
Paths listed in read_write receive full access.
All other paths are inaccessible.
Landlock setup runs in two phases. The parent supervisor probes the kernel ABI and opens the configured path file descriptors before forking. The child then applies the ruleset with restrict_self() after privilege drop. At startup, OpenShell emits the selected ABI version and the applied read-only and read-write rule counts so you can confirm what the kernel accepted.
The policy separates filesystem paths into read-only and read-write groups.
OpenShell validates policies before they take effect.
The sandbox supervisor drops privileges, applies seccomp filters, and enforces process-level restrictions during startup.
The sandbox process runs as a non-root user after explicit privilege dropping.
OpenShell applies seccomp in two phases. A narrow supervisor-startup prelude runs before CLI parsing and async runtime initialization, then the child process receives the broader runtime seccomp filter after privilege drop.
The sandbox supervisor applies enforcement in a specific order during process startup.
This ordering is intentional: named network-namespace setup still relies on privileged helpers, and privilege dropping still needs /etc/group and /etc/passwd, which Landlock subsequently restricts.
nft probes.PR_SET_NO_NEW_PRIVS plus the early syscall denylist) synchronized across runtime threads.setns) in child pre_exec.initgroups + setgid + setuid).RLIMIT_CORE=0, plus PR_SET_DUMPABLE=0 on Linux).OpenShell routes all inference traffic through the gateway to isolate provider credentials from the sandbox.
inference.localThe proxy intercepts HTTPS CONNECT requests to inference.local and routes matching inference API requests through the sandbox-local router.
The agent never receives the provider API key.
The gateway secures communication between the CLI, sandbox workloads, and external clients with mutual TLS and token-based authentication.
Gateway transport uses TLS, with client certificate checks available where the deployment provides a client CA. Local single-user Docker, Podman, and VM gateways can use the verified client certificate as user authentication. Kubernetes deployments use the certificate bundle for transport and sandbox supervisor connectivity only; configure OIDC or a trusted access proxy for user authentication.
SSH connections to sandboxes travel through the gateway over the sandbox supervisor’s authenticated control path. Each SSH connect call also carries a short-lived session token scoped to a specific sandbox. The sandbox never exposes an SSH port on the network. Its SSH daemon listens on a local Unix socket that only the sandbox’s own supervisor process can reach.
The following patterns weaken security without providing meaningful benefit.