Skip to content
OpenShell

OpenShell Security Best Practices for Controls, Risks, and Configuration Guidance

A guide to every configurable security control in OpenShell: defaults, what you can change, and the risks of each choice.

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.

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.

Layer What it protects Enforcement point Changeable at runtime
Network Unauthorized outbound connections and data exfiltration. CONNECT proxy + OPA policy engine Yes. Use openshell policy update, openshell policy set, or operator approval in the TUI.
Filesystem System binary tampering, credential theft, config manipulation. Landlock LSM (kernel level) No. Requires sandbox re-creation.
Process Privilege escalation, fork bombs, dangerous syscalls. Seccomp BPF + non-root identity without Linux capabilities No. Requires sandbox re-creation.
Provider credentials Credential exposure and unauthorized service access. Network policy plus profile endpoint binding and proxy substitution Yes. Attach or detach providers and update dynamic policy.

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.

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.

Aspect Detail
Default All egress denied. Only endpoints listed in network_policies can receive traffic.
What you can change Add entries to network_policies in the policy YAML. Apply statically at creation (--policy) or dynamically (openshell policy update for incremental changes, openshell policy set for full replacement).
Risk if relaxed Each allowed endpoint is a potential data exfiltration path. The agent can send workspace content, credentials, or conversation history to any reachable host.
Recommendation Add only endpoints the agent needs for its task. Start with a minimal policy and use denied-request logs (openshell logs <name> --source sandbox) to identify missing endpoints.

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.

Aspect Detail
Default Always active. The sandbox cannot bypass the proxy at the network level.
What you can change The compute driver establishes the fence. Kubernetes operators must provide a CNI that enforces ingress and egress NetworkPolicy.
Risk if bypassed A missing or ineffective outer fence removes an independent barrier against direct connections that bypass mediation.
Recommendation Keep the driver-managed network restrictions intact. On Kubernetes, verify CNI enforcement and restrict who can modify sandbox network policies and role labels.

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.

Aspect Detail
Default Disabled. Set gatewayConfig.openshell.drivers.kubernetes.enable_user_namespaces: true in Helm values to enable cluster-wide.
What you can change Enable cluster-wide through Helm or gateway config. Override per-sandbox through the user_namespaces field on SandboxTemplate in the API.
Prerequisites Kubernetes 1.33+ with user namespace support available (beta through 1.35, GA in 1.36+), a container runtime that supports user namespaces (containerd 2.0+, CRI-O 1.25+), and Linux 5.12+ for ID-mapped mounts.
Risk if enabled with GPU NVIDIA device plugin compatibility with user namespaces is unverified. OpenShell logs a warning when both GPU and user namespaces are active on the same sandbox.
Recommendation Enable on non-GPU clusters running Kubernetes with user namespace support available (1.33+ beta, 1.36+ GA) for stronger host isolation. Test GPU workloads separately before enabling on GPU clusters.

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.

Aspect Detail
Default Every network_policies entry requires a binaries list. Only listed binaries can reach the associated endpoints. Binary paths support glob patterns (* for one path component, ** for recursive).
What you can change Add binaries to an endpoint entry. Use glob patterns for directory-scoped access (for example, /sandbox/.vscode-server/**).
Risk if relaxed Broad glob patterns (like /**) allow any leaf or ancestor executable to authorize the endpoint, defeating the purpose of binary-scoped enforcement.
Recommendation Scope binaries to the specific leaf or launcher executables that need each endpoint. Use narrow globs when the exact path varies (for example, across Python virtual environments). Restart the sandbox runtime after intentionally replacing an executable at an authorized path so a new runtime can establish a new pin.

The protocol field on an endpoint controls whether the proxy inspects individual HTTP requests inside the tunnel.

Aspect Detail
Default Endpoints without a protocol field apply no request rules. The proxy checks host, port, and binary, still terminates TLS and parses HTTP requests, and requires the request authority to match the destination, but it allows any HTTP method and path. Non-HTTP traffic is relayed without inspection. protocol: tcp endpoints also apply no request rules, and tls: skip endpoints relay traffic without terminating TLS. Provider-credentialed endpoints reject uninspected modes unless an operator explicitly opts in.
What you can change Add protocol: rest to enable per-request HTTP method/path inspection, protocol: websocket to inspect RFC 6455 upgrade handshakes and client text messages, or protocol: graphql to inspect GraphQL-over-HTTP operation type, operation name, and root fields. WebSocket endpoints can also use GraphQL operation rules for GraphQL-over-WebSocket messages. Pair inspected protocols with rules or access presets (full, read-only, read-write). REST endpoints that need credential placeholders in supported text request bodies can set request_body_credential_rewrite: true. Set allow_uninspected_credentials: true only as an explicit exception for credentialed traffic that cannot use an inspected path.
Risk if relaxed Endpoints without request rules allow the agent to send any request or data to the destination after the connection is permitted. The proxy does not restrict HTTP methods, paths, or GraphQL operations. Adding access: full with L7 inspection enables observability but permits all inspected actions.
Recommendation Use protocol: rest with specific rules for APIs where intent is encoded in method and path. Add request_body_credential_rewrite: true only for REST APIs that require OpenShell-managed credentials in UTF-8 JSON, form, or text request bodies. Use protocol: graphql for GraphQL-over-HTTP APIs where destructive operations are body-encoded. Use protocol: websocket for RFC 6455 endpoints, with explicit GET and WEBSOCKET_TEXT rules for raw text protocols or explicit GraphQL operation rules for GraphQL-over-WebSocket. Prefer access: read-only or explicit allowlists, and deny hash-only persisted queries unless you maintain a trusted registry. Use protocol: tcp for native non-HTTP clients such as databases, and refer to Allow Native TCP for when to add tls: skip. For WebSocket endpoints that must carry placeholder credentials in client text frames, add websocket_credential_rewrite: true.

When L7 inspection is active, the enforcement field controls whether the proxy blocks or logs rule violations.

Aspect Detail
Default audit. The proxy logs violations but forwards traffic.
What you can change Set enforcement: enforce to block requests that do not match any rules entry. Denied requests receive a 403 Forbidden response with a JSON body describing the violation.
Risk if relaxed audit mode provides visibility but does not prevent unauthorized actions. An agent can still perform write or delete operations on an API even if the rules would deny them.
Recommendation Start with audit to understand traffic patterns and verify that rules are correct. Switch to enforce after you validate that the rules match the intended access pattern.

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.

Aspect Detail
Default Auto-detect and terminate. OpenShell generates the sandbox CA at startup and injects it into the process trust stores (NODE_EXTRA_CA_CERTS, DENO_CERT, SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, GIT_SSL_CAINFO).
What you can change Set tls: skip on an endpoint to disable TLS detection and termination for that endpoint. Use this for client-certificate mTLS to upstream or non-standard binary protocols.
Risk if relaxed tls: skip disables placeholder credential rewriting, dynamic token grant injection, and L7 inspection for that endpoint. The proxy relays encrypted traffic without seeing the contents.
Recommendation Use auto-detect (the default) for most endpoints. Use tls: skip only when the upstream requires the client’s own TLS certificate (mTLS) or uses a non-HTTP protocol. A provider-credentialed endpoint also requires the explicit allow_uninspected_credentials: true exception.

After OPA policy allows a connection, the proxy resolves DNS and rejects undeclared internal destinations.

Aspect Detail
Default The proxy blocks private IPs for undeclared, wildcard, and hostless endpoints, and for endpoints added through the policy advisor. Exact hostnames declared in user policy may resolve to private RFC 1918 addresses. Loopback (127.0.0.0/8), link-local (169.254.0.0/16), and unspecified (0.0.0.0) addresses are always blocked and cannot be overridden with allowed_ips.
What you can change Declare a known internal service as an exact host endpoint, or add allowed_ips (CIDR notation) to an endpoint to permit specific private IP ranges for wildcard or hostless policies. The supervisor resolver is authoritative for hostname-only authorization. Linux explicit-proxy paths with access to the workload process namespace may use sandbox /etc/hosts entries, including Kubernetes hostAliases, for ordinary endpoints only when the endpoint has allowed_ips; every resolved address is then checked against the allowlist. Driver-managed host-gateway aliases use a separate trusted IP pin. Policies with allowed_ips entries that overlap loopback, link-local, or unspecified addresses fail to load with a clear validation error.
Risk if relaxed Without SSRF protection, a misconfigured policy could allow the agent to reach cloud metadata services (169.254.169.254), internal databases, or other infrastructure endpoints through DNS rebinding.
Recommendation Prefer exact hostname endpoints for stable internal services. Use allowed_ips when you need hostless or wildcard authorization, and scope the CIDR as narrowly as possible (for example, 10.0.5.20/32 for a single host). Loopback, link-local, and unspecified addresses are always blocked regardless of allowed_ips. On a deployment that supports sandbox host aliases, declare both host: searxng.local and allowed_ips: [192.168.1.105/32] before relying on a Kubernetes hostAliases mapping; the alias changes resolution while the allowlist supplies the trusted address constraint. The policy advisor does not propose rules for always-blocked destinations and still requires a separate allowed_ips edit for private-IP endpoints.

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.

Aspect Detail
Default Enabled. The proxy blocks unlisted endpoints and requires approval.
What you can change Approved endpoints persist across sandbox restarts within the same sandbox instance. They reset when the sandbox is destroyed and recreated.
Risk if relaxed Approving an endpoint permanently widens the running sandbox’s policy. Review each request before approving.
Recommendation Use operator approval for exploratory work. For recurring endpoints, add them to the policy YAML with appropriate binary and path restrictions. To reset all approved endpoints, destroy and recreate the sandbox.

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.

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.

Aspect Detail
Default The mandatory baseline always requires Landlock ABI 3 or newer. The additional filesystem policy defaults to compatibility: best_effort, which may skip unavailable policy paths and emits a High-severity OCSF DetectionFinding when that policy cannot be fully applied.
What you can change Set compatibility: hard_requirement to reject startup when the additional filesystem policy cannot be applied. Neither setting relaxes the private-file baseline.
Risk if relaxed A skipped additional policy can expose otherwise permitted image or workspace files to the agent. It cannot grant access to files excluded by the mandatory baseline.
Recommendation Require Linux 6.2 or newer with Landlock enabled, or a qualified distribution backport providing ABI 3. Use hard_requirement where all configured filesystem restrictions must apply. Investigate High-severity Landlock findings rather than treating them as a supported degraded security mode.

The policy separates filesystem paths into read-only and read-write groups.

Aspect Detail
Default System paths (/usr, /lib, /etc, /var/log) are read-only. The resolved working directory and /tmp are read-write. List any other path your workload needs, such as /app.
What you can change Add or remove paths in filesystem_policy.read_only and filesystem_policy.read_write.
Risk if relaxed Making system paths writable lets the agent replace binaries, modify TLS trust stores, or change DNS resolution. Validation rejects broad read-write paths (like /).
Recommendation Keep system paths read-only. If the agent needs additional writable space, add a specific subdirectory.

OpenShell validates policies before they take effect.

Constraint Behavior
Paths must be absolute (start with /). Rejected with INVALID_ARGUMENT.
Paths must not contain .. traversal. Rejected with INVALID_ARGUMENT.
Read-write paths must not be overly broad (for example, / alone). Rejected with INVALID_ARGUMENT.
Each path must not exceed 4096 characters. Rejected with INVALID_ARGUMENT.
Combined read_only + read_write paths must not exceed 256. Rejected with INVALID_ARGUMENT.

The compute driver establishes the workload identity and outer boundary. The sandbox runtime validates that environment and applies process controls before launching agent code.

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.

Aspect Detail
Default The compute driver selects a non-root identity. Docker and Podman use the image’s OCI USER as a per-field fallback. Agent children inherit the runtime identity. Before exec, the runtime disables core dumps with RLIMIT_CORE=0 and sets PR_SET_DUMPABLE=0.
What you can change Set either or both run_as_user and run_as_group fields in the process section. Each explicit field takes precedence and must be sandbox or a numeric UID/GID from 1 through 4294967294. Docker and Podman may use named identities through OCI USER fallback. Root and the invalid identity sentinel are always rejected.
Risk if relaxed A numeric identity inherits every permission granted to the same UID/GID on image files, mounted volumes, or devices. Low IDs often collide with system accounts and groups.
Recommendation Use a dedicated non-root image identity or explicit numeric policy identity. Do not attempt to set root.

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.

Aspect Detail
Startup prelude After runtime qualification and bootstrap validation, the sandbox installs a synchronized filter before creating the process launcher and async runtime. It blocks mount, the new mount API syscalls, pivot_root, umount2, bpf, perf_event_open, userfaultfd, module-loading syscalls, and kexec. The runtime already has PR_SET_NO_NEW_PRIVS and no Linux capabilities.
Socket domains The filter allows only AF_UNIX, AF_NETLINK, and the brokered AF_INET and AF_INET6 families. Every other family, including AF_PACKET, AF_VSOCK, AF_RXRPC, AF_SMC, AF_KCM, and AF_ALG, fails with EPERM, and socketpair(2) is limited to AF_UNIX. AF_NETLINK is partially allowed: only NETLINK_ROUTE (protocol 0) is permitted so that getifaddrs(3) works; all other netlink protocols are blocked. Write operations via NETLINK_ROUTE still require CAP_NET_ADMIN, which the sandbox does not grant.
Runtime unconditional syscall blocks memfd_create, ptrace, bpf, process_vm_readv, process_vm_writev, pidfd_open, pidfd_getfd, pidfd_send_signal, io_uring_setup, mount, fsopen, fsconfig, fsmount, fspick, move_mount, open_tree, setns, umount2, pivot_root, userfaultfd, perf_event_open.
Conditional syscall blocks execveat with AT_EMPTY_PATH, unshare and clone with CLONE_NEWUSER, and seccomp(SECCOMP_SET_MODE_FILTER) are denied with EPERM.
What you can change This is not a user-facing knob. OpenShell enforces it automatically.
Risk if relaxed The blocked syscalls support container escape (mount, pivot_root, move_mount, namespace creation), cross-process observation (ptrace, process_vm_readv, pidfd_*), raw kernel bypass (bpf, io_uring_setup, perf_event_open), and filter evasion (seccomp, userfaultfd).
Recommendation No action needed. OpenShell enforces this automatically.

The built-in Linux sandbox runtime applies enforcement before agent execution.

  1. The compute driver prepares the outer boundary and non-root runtime identity. VM guest preparation drops privileges before starting the runtime.
  2. The runtime verifies its identity, empty capability sets, no_new_privs, and required kernel enforcement features.
  3. The runtime validates its bootstrap, installs the startup seccomp prelude, and creates the process launcher with network-mediation filters that its children inherit.
  4. The supervisor verifies and confirms the boundary before allowing launch.
  5. The child applies core-dump hardening (RLIMIT_CORE=0 and PR_SET_DUMPABLE=0).
  6. The child applies the mandatory Landlock baseline and configured filesystem restrictions.
  7. The child installs seccomp self-protection and runtime socket-domain and syscall filters, then executes the agent.

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.

Aspect Detail
Default No model-provider access. A sandbox must attach a provider and policy must admit the native endpoint and calling binary.
Credential boundary The placeholder resolves only for hosts, ports, and paths authorized by the provider profile.
What you can change Attach or detach providers and adjust the profile or sandbox policy. Model and timeout configuration remain in the native client.
Risk if relaxed Broad endpoint paths or binary globs can expose more of a provider’s API than the workload needs. allow_uninspected_credentials removes L7 visibility and should be exceptional.
Recommendation Use narrow endpoint paths and binaries, inspect the effective policy, and keep credentials in provider records rather than workload environment configuration.

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. 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.

Aspect Detail
Default A configured client CA without OIDC enables mTLS user authentication. Sandbox supervisors use CA-only TLS plus gateway-minted sandbox JWTs. TLS-enabled loopback gateways also accept plaintext HTTP for sandbox service hostnames by default.
What you can change Configure mTLS user authentication, OIDC, or a trusted access proxy at the gateway; enable server.auth.allowUnauthenticatedUsers=true only for trusted local Kubernetes development or a fully trusted proxy; disable TLS only for trusted reverse-proxy setups; or disable loopback service HTTP with --enable-loopback-service-http=false.
Risk if relaxed Disabling TLS removes transport-level protection entirely. Allowing unauthenticated users removes the gateway user-auth boundary and must not be exposed to shared or public networks. Mounting a user client certificate into a sandbox would collapse user and sandbox trust boundaries. Loopback service HTTP is local-only and rejects cross-origin browser requests, but any local process can still reach exposed service URLs directly.
Recommendation Keep sandbox identity separate from user identity: expose only the gateway CA to sandboxes and require sandbox JWTs. Use managed OIDC or a trusted access proxy when certificate distribution is unsuitable for shared users.

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.

Aspect Detail
Default Session tokens expire after 24 hours. Concurrent connections are limited to 3 per token, 20 SSH relays per sandbox, and 20 service forwards per sandbox.
What you can change Configure ssh_session_ttl_secs (set to 0 for no expiry), max_ssh_connections_per_sandbox, and max_service_connections_per_sandbox.
Risk if relaxed Longer TTLs or no expiry increase the window for stolen token reuse. Higher connection limits increase the blast radius of a compromised token.
Recommendation Keep the 24-hour default. Monitor connection counts through the TUI.

The following patterns weaken security without providing meaningful benefit.

Mistake Why it matters What to do instead
Omitting an inspected protocol on REST or WebSocket API endpoints Without protocol: rest or protocol: websocket, the proxy applies no request rules. It allows any HTTP method and path after checking host, port, and binary, and does not inspect WebSocket text messages. Add protocol: rest or protocol: websocket with specific rules to enable method and path control.
Using access: full when finer rules would suffice access: full with protocol: rest or protocol: websocket enables inspection but allows all methods and paths for that protocol. Use access: read-only or explicit rules to restrict what the agent can do at the L7 level.
Adding endpoints permanently when operator approval would suffice Adding endpoints to the policy YAML makes them permanently reachable across all instances. Use operator approval. Approved endpoints persist within the sandbox instance but reset on re-creation.
Using broad binary globs A glob like /** allows any binary to reach the endpoint, defeating binary-scoped enforcement. Scope globs to specific directories (for example, /sandbox/.vscode-server/**).
Skipping TLS termination on HTTPS APIs Setting tls: skip disables placeholder credential rewriting, dynamic token grant injection, and L7 inspection. Use the default auto-detect behavior unless the upstream requires client-certificate mTLS.
Setting enforcement: enforce before auditing Jumping to enforce without first running in audit mode risks breaking the agent’s workflow. Start with audit, review the logs, and switch to enforce after you validate the rules.
Pasting raw stack traces in bug reports Some frameworks include the full request config — including credentials — in error objects. The sandbox does not scrub application-level output. Inspect error output before sharing. Redact any credentials, API keys, or tokens.

We are a Cloud Native Computing Foundation sandbox project.