OpenShell Security Best Practices for Controls, Risks, and Configuration Guidance
OpenShell enforces sandbox security across four layers: network, filesystem, process, and provider credentials. 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 Architecture.
If you use NemoClaw, its Security Best Practices guide covers additional entrypoint-level controls, policy presets, provider trust tiers, and posture profiles specific to the NemoClaw blueprint.
Enforcement Layers
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.
Network Controls
The trusted supervisor’s proxy and OPA policy engine enforce network policy. The sandbox runtime mediates network operations, and the compute driver provides an outer network fence.
Deny-by-Default Egress
The sandbox runtime sends outbound connection requests over the authenticated
Sandbox Protocol channel to the supervisor. The supervisor 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.
Network Namespace Isolation
Each compute driver blocks direct workload egress using its runtime’s network
controls. Docker and Podman disable networking on the workload container and use
a private Unix socket for the Sandbox Protocol. Kubernetes uses NetworkPolicy
to permit only the protected control channel. VM guests have no network device
and use vsock. Ignoring proxy environment variables does not bypass mediation.
See Runtime Boundaries.
User Namespace Isolation
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.
Binary Identity Binding
OpenShell binds each connection to executable identity observed by the trusted isolation boundary. Network policy can authorize either the connection-owning executable or one of its executable ancestors. OpenShell pins every authorization-capable path to its first runtime-observed SHA256 digest (trust on first use), and a later digest mismatch triggers an immediate deny. Missing or conflicting integrity evidence also fails closed. Command-line paths remain diagnostic context and never authorize access.
L4-Only vs L7 Inspection
The protocol field on an endpoint controls whether the proxy inspects individual HTTP requests inside the tunnel.
Enforcement Mode (audit vs enforce)
When L7 inspection is active, the enforcement field controls whether the proxy blocks or logs rule violations.
TLS Handling
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.
SSRF Protection
After OPA policy allows a connection, the proxy resolves DNS and rejects undeclared internal destinations.
Operator Approval
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.
Filesystem Controls
Landlock LSM restricts which paths the sandbox process can read or write at the kernel level.
Landlock LSM
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.
The sandbox installs a mandatory Landlock baseline before running agent code. It requires ABI 3 or newer, introduced in Linux 6.2, so denied writes include file truncation. The baseline hides the private channel and bootstrap root from the agent by granting access only to explicitly opened, permitted root children; it never grants the filesystem root or follows a root-level symlink when constructing that allowlist. Startup fails if this baseline cannot be enforced. The configured filesystem policy adds restrictions on top of the baseline.
Read-Only vs Read-Write Paths
The policy separates filesystem paths into read-only and read-write groups.
Path Validation
OpenShell validates policies before they take effect.
Process Controls
The compute driver establishes the workload identity and outer boundary. The sandbox runtime validates that environment and applies process controls before launching agent code.
Privilege Drop
The sandbox runtime starts as a non-root user with no Linux capabilities and
no_new_privs set. It rejects an environment that does not meet these
requirements. VM startup includes trusted privileged guest preparation, which
drops UID, GID, and capabilities before entering the qualified runtime.
Seccomp Filters
OpenShell installs a startup seccomp prelude in the already qualified sandbox runtime. Workload children inherit network-mediation filters from the process launcher. Before exec, each child applies Landlock, seccomp self-protection, and the runtime socket and syscall filters.
Enforcement Application Order
The built-in Linux sandbox runtime applies enforcement before agent execution.
- The compute driver prepares the outer boundary and non-root runtime identity. VM guest preparation drops privileges before starting the runtime.
- The runtime verifies its identity, empty capability sets,
no_new_privs, and required kernel enforcement features. - The runtime validates its bootstrap, installs the startup seccomp prelude, and creates the process launcher with network-mediation filters that its children inherit.
- The supervisor verifies and confirms the boundary before allowing launch.
- The child applies core-dump hardening (
RLIMIT_CORE=0andPR_SET_DUMPABLE=0). - The child applies the mandatory Landlock baseline and configured filesystem restrictions.
- The child installs seccomp self-protection and runtime socket-domain and syscall filters, then executes the agent.
Inference Controls
Inference providers use the same endpoint-bound credential mechanism as other providers. Attach a profile-backed provider only to sandboxes that need it. The agent receives an opaque placeholder, not the real API key or access token.
Gateway Security
The gateway secures communication between the CLI, sandbox workloads, and external clients with mutual TLS and token-based authentication.
mTLS
Gateway transport uses TLS, with client certificate checks available where the deployment provides a client CA. mTLS user authentication is gateway policy and does not depend on the compute driver. Sandbox supervisors receive only the gateway CA and authenticate API calls with gateway-minted sandbox JWTs.
SSH Tunnel 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.
Service forwards (openshell forward) use the same relay path but carry no session token. The gateway authorizes each forwarded connection against the caller’s gateway identity and workspace membership, and the per-sandbox service forward limit applies.
Common Mistakes
The following patterns weaken security without providing meaningful benefit.
Related Topics
- Sandbox Policies for how policies are evaluated and applied.
- Manage Sandbox Policies for applying and iterating on sandbox policies.
- Policy Schema for the full field-by-field YAML reference.
- Default Policy for the built-in default policy breakdown.
- Gateway Auth for gateway authentication details.
- Architecture for the system architecture.
- NemoClaw Security Best Practices for entrypoint-level controls (capability drops, PATH hardening, build toolchain removal), policy presets, provider trust tiers, and posture profiles.