Reference: OpenShell Technical Internals

1. Container Technology

OpenShell supports multiple compute backends:

Backend	Use Case	Notes
Docker	Local development (primary)	Uses host networking for loopback gateway access
Podman	Rootless containers	Alternative to Docker
MicroVM (libkrun)	Stronger isolation	VM-level isolation
Kubernetes	Production/scale	Sidecar topology with init container

The supervisor binary is either bind-mounted or extracted from a configured image.

Source: NVIDIA OpenShell Documentation

2. Landlock LSM (Filesystem Isolation)

What it is: Linux Security Module for kernel-level filesystem access control (requires kernel 5.13+, Ubuntu 22.04+).

Default mode: compatibility: best_effort - applies rules when kernel supports them.

Filesystem Policy

filesystem_policy:
  read_only:
    - /usr
    - /lib
    - /proc
    - /dev/urandom
    - /app
    - /etc
    - /var/log
  read_write:
    - /sandbox
    - /tmp
    - /dev/null
    - /dev/pts

Key behaviors:

Supervisor enriches baseline paths for proxy support files and GPU device paths
Inode-type tailoring adjusts rules based on whether paths are directories or files
Layout changes require sandbox re-creation (not hot-reloadable)

Source: NVIDIA OpenShell Security Documentation

3. Linux Namespaces

OpenShell uses namespaces for isolation:

Network namespace: Forces all agent egress through local CONNECT proxy
Loopback metadata server: Inside namespace, serves credential placeholders
Mount namespace: Children enter private mount namespace where sensitive directories (SPIFFE socket paths) are hidden before privilege drop

Kubernetes Sidecar Topology

Uses init container with NET_ADMIN capability for pod-network nftables setup.

Source: NVIDIA OpenShell Documentation

4. Resource Limits (Cgroups)

# Process limit (default 512)
ulimit -u 512

# File descriptor limit (default 65536)
ulimit -n 65536

# Docker runtime equivalent
docker run --ulimit nproc=512:512 --ulimit nofile=65536:65536 ...

Note: These are best-effort - logs warning if runtime restricts ulimit modification.

Source: NVIDIA OpenShell Documentation

5. Seccomp Filters

OpenShell uses seccomp-bpf for syscall filtering:

Sets PR_SET_NO_NEW_PRIVS using prctl() inside sandbox process
BPF socket domain filters block dangerous syscalls including raw socket paths that bypass proxy

Application Order (Critical!)

Namespace entry
Privilege drop
Landlock
Seccomp

# Docker compose config
security_opt:
  - no-new-privileges:true

Source: NVIDIA OpenShell Security Documentation

6. Capability Dropping

Initial Drop (via capsh at entrypoint)

cap_sys_admin cap_sys_ptrace cap_net_raw cap_dac_override cap_sys_chroot cap_fsetid cap_setfcap cap_mknod cap_audit_write cap_net_bind_service

During setpriv Step-Down

cap_setuid cap_setgid cap_fowner cap_chown cap_kill

Fail-closed behavior: Supervisor retains CAP_SETPCAP to clear bounding set. Spawn aborts unless bounding set ends up empty.

# Strict mode - refuse to start if caps can't be dropped
NEMOCLAW_REQUIRE_CAP_DROP=1

Source: NVIDIA OpenShell Security Documentation

7. Policy Engine Architecture

Core technology: Uses Open Policy Agent (OPA) for policy evaluation.

Policy Proxy Functions

Destination rules evaluation
Binary identity verification
SSRF protection
TLS/L7 inspection
Credential injection
Inference interception

Binary Identification

Reads /proc/<pid>/exe for kernel-trusted path
Walks process tree for ancestors
Computes SHA256 hash on first use

Hot-reloadability:

✓ Network policy - hot-reloadable
✗ Filesystem/process policies - locked at creation

Source: NVIDIA OpenShell Documentation

8. Network Traffic Interception

All sandbox egress flows through OpenShell's CONNECT proxy.

Two Inspection Modes

Mode	Checks	Use Case
L4-only	Host, port, binary	Fast, minimal overhead
L7 inspection	Auto-detects/terminates TLS, evaluates HTTP method/path	Deep inspection

Protocol Options

rest, websocket, json-rpc, mcp

TLS Handling

Proxy terminates TLS with sandbox's ephemeral CA for HTTP inspection.

Host Wildcard Patterns

# Single label wildcard
*.example.com

# Recursive wildcard
**.example.com

# Intra-label wildcard
*-aiplatform.googleapis.com

L7 REST Policy Example

protocol: rest
rules:
  - methods: [GET, POST]
    paths: ["/api/**"]

# Binary-scoped restriction
binaries:
  - /usr/bin/git

Source: NVIDIA OpenShell Documentation

9. OpenShell CLI Architecture

Language: Written in Rust (90.7% of codebase)

Core Crates

openshell-cli - Command-line interface
openshell-sandbox - Sandbox management
openshell-policy - Policy evaluation
openshell-supervisor-network - Network supervision
openshell-supervisor-process - Process supervision
openshell-gateway-interceptors - Request interception

Compute Drivers

openshell-driver-docker
openshell-driver-podman
openshell-driver-kubernetes
openshell-driver-vm

Gateway communicates with drivers via gRPC using compute_driver.proto.

Source: GitHub NVIDIA/OpenShell

10. OpenShell CLI Commands

# Create sandbox with agent
openshell sandbox create -- <agent>

# Connect via SSH
openshell sandbox connect [name]

# List sandboxes
openshell sandbox list

# Apply policy
openshell policy set <name> --policy file.yaml

# Get current policy
openshell policy get <name>

# Configure inference
openshell inference set --provider <p> --model <m>

# Stream logs
openshell logs [name] --tail

# Terminal UI
openshell term

Source: NVIDIA OpenShell Documentation

11. Sandbox Provisioning Process

Compute runtime starts workload with sandbox identity, callback endpoint, TLS material, image metadata
Supervisor loads policy from local files or gateway
Prepares isolation: filesystem access, process restrictions, network namespace routing, trust stores, credential resolution
Starts policy proxy and local SSH server
Opens supervisor session to gateway
Launches agent command as restricted sandbox user

Key detail: Supervisor starts as root, prepares isolation, then agent child runs as unprivileged user with restrictions applied.

Source: NVIDIA OpenShell Documentation

12. Three-Tier Runtime Model

Tier	Components	Role
Tier 1	CLI / SDK / TUI	User interfaces
Tier 2	Gateway	Authenticated control plane (API access, state, policy delivery)
Tier 3	Supervisor	Runs inside sandbox as local security boundary, launches agent as restricted child

Communication: CLI/SDK → gRPC/HTTP → Gateway → Supervisor

Source: NVIDIA OpenShell Documentation

13. Security Environment Variables

# Disable EC2 metadata access (SSRF protection)
AWS_EC2_METADATA_DISABLED=true

# Require capability drop or refuse to start
NEMOCLAW_REQUIRE_CAP_DROP=1

# Gateway bind to loopback only
NEMOCLAW_GATEWAY_BIND_ADDRESS=127.0.0.1

# Hardened PATH
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Source: NVIDIA OpenShell Security Best Practices

14. Installation Methods

# Binary install
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh

# PyPI install (requires uv)
uv tool install -U openshell

# Helm chart (experimental)
helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart

Source: GitHub NVIDIA/OpenShell

OpenShell Technical Internals

Related Lessons

1. Container Technology

2. Landlock LSM (Filesystem Isolation)

Filesystem Policy

3. Linux Namespaces

Kubernetes Sidecar Topology

4. Resource Limits (Cgroups)

5. Seccomp Filters

Application Order (Critical!)

6. Capability Dropping

Initial Drop (via capsh at entrypoint)

During setpriv Step-Down

7. Policy Engine Architecture

Policy Proxy Functions

Binary Identification

8. Network Traffic Interception

Two Inspection Modes

Protocol Options

TLS Handling

Host Wildcard Patterns

L7 REST Policy Example

9. OpenShell CLI Architecture

Core Crates

Compute Drivers

10. OpenShell CLI Commands

11. Sandbox Provisioning Process

12. Three-Tier Runtime Model

13. Security Environment Variables

14. Installation Methods