Understand Process Controls

OpenShell limits the capabilities available to managed sandbox processes. NemoClaw entrypoints retain only direct root-to-user transitions and resource-limit hooks for the paths that still consume them.

OpenShell enforces additional process-level controls not covered here, including seccomp BPF socket domain filters and a specific enforcement application order (namespace entry, privilege drop, Landlock, seccomp). Refer to the Process Controls section of the OpenShell Security Best Practices.

Capability Ownership

OpenShell owns capability enforcement for managed agent processes. The OpenClaw and Hermes entrypoints do not inspect, drop, record, or reconcile Linux capabilities. This keeps one enforcement owner for the entrypoint, later exec processes, and connect shells.

A direct container runtime can explicitly override the image user to root. That compatibility path retains the existing capsh bounding-set drop and supports NEMOCLAW_REQUIRE_CAP_DROP=1 for fail-closed verification. It is not used by OpenShell-managed launches and is not a substitute for container-runtime capability configuration.

The managed images install setpriv from util-linux and require it when the entrypoint switches from root to the sandbox and gateway users. When CAP_SETPCAP is available, the same setpriv operation removes the remaining privilege-separation capabilities from the child process at the same time as the user change. That direct root-to-user transition is separate from managed OpenShell enforcement and removes cap_setuid, cap_setgid, cap_fowner, cap_chown, and cap_kill from the child bounding set when the runtime permits it.

For root-to-user transitions, the extra bounding-set capability drop is best effort. If capsh or CAP_SETPCAP is unavailable, the root entrypoint logs a warning and uses setpriv without the extra bounding-set drop.

When a root entrypoint must change identity, it fails closed if setpriv is unavailable instead of starting an agent service as root.

Aspect	Detail
Default	OpenShell owns capability enforcement for managed processes. Root-to-user transitions outside that topology still require `setpriv`.
What you can change	Select the required OpenShell enforcement posture. When launching with `docker run` directly, pass `--cap-drop=ALL` at the container runtime. `NEMOCLAW_REQUIRE_CAP_DROP=1` keeps the retained direct-root compatibility check fail closed.
Risk if relaxed	`CAP_SYS_ADMIN` and `CAP_SYS_PTRACE` expand kernel and process attack surface. `CAP_NET_RAW` allows raw socket access for network sniffing. `CAP_DAC_OVERRIDE` bypasses filesystem permission checks.
Recommendation	Keep OpenShell enforcement enabled. For direct containers, make the container runtime the capability owner and pass `--cap-drop=ALL`.

Gateway Process Isolation

The stock Hermes image and the managed-image publication workflow set the OCI default user to sandbox for OpenShell 0.0.116. The supervisor, agent gateway, and agent commands share that UID.

Aspect	Detail
Default	The OCI default user is `sandbox`, as required by OpenShell 0.0.116.
What you can change	A direct container runtime outside OpenShell can override the image user. A root override can provide separate gateway and agent UIDs.
Risk if relaxed	A same-UID agent can signal the agent gateway and attempt to imitate its process shape. Running agent commands as `root` also expands filesystem access and container escape impact.
Recommendation	Keep the sandbox entrypoint under OpenShell. Use root only for a direct-container topology that requires separate gateway and agent UIDs.

No New Privileges

The no-new-privileges flag prevents processes from gaining additional privileges through setuid binaries or capability inheritance.

Aspect	Detail
Default	OpenShell sets `PR_SET_NO_NEW_PRIVS` using `prctl()` inside the sandbox process as part of the seccomp filter setup. The NemoClaw Compose example also shows the equivalent `security_opt: no-new-privileges:true` setting.
What you can change	OpenShell’s seccomp path enforces this inside the sandbox. It is not a user-facing knob.
Risk if relaxed	Without this flag, a compromised process could execute a setuid binary to escalate to root inside the container, then attempt container escape techniques.
Recommendation	No action needed. OpenShell enforces this automatically when the sandbox network policy is active. When an OpenShell-managed topology starts an entrypoint as a non-root user, this flag prevents that process from changing users.

Process Limit

A process limit caps the number of processes the sandbox user can spawn. The entrypoint sets both soft and hard limits using ulimit -u 512. This behavior is best effort. If the container runtime restricts ulimit modification, the entrypoint logs a security warning and continues without the limit.

Aspect	Detail
Default	512 processes (`ulimit -u 512`), best-effort.
What you can change	Increase or decrease the limit with `--ulimit nproc=N:N` in `docker run` or the `ulimits` section in Compose. The runtime-level ulimit takes precedence over the entrypoint’s setting.
Risk if relaxed	Removing or raising the limit makes the sandbox vulnerable to fork-bomb attacks, where a runaway process spawns children until the host runs out of resources. If the entrypoint cannot set the limit (logs `[SECURITY] Could not set soft/hard nproc limit`), the container runs without process limits.
Recommendation	Keep the default at 512. If the agent runs workloads that spawn many child processes (such as parallel test runners), increase to 1024 and monitor host resource usage. If the entrypoint logs a warning about ulimit restrictions, set the limit through the container runtime instead.

Open File Descriptor Limit

An open file descriptor limit caps the number of files, sockets, and pipes the sandbox user can hold open at once. The entrypoint sets both soft and hard limits using ulimit -n 65536. This behavior is best effort. If the container runtime restricts ulimit modification, the entrypoint logs a security warning and continues without the limit.

Aspect	Detail
Default	65536 open files, soft and hard (`ulimit -n 65536`), best-effort.
What you can change	Increase or decrease the limit with `--ulimit nofile=N:N` in `docker run` or the `ulimits` section in Compose. The runtime-level ulimit takes precedence over the entrypoint’s setting.
Risk if relaxed	Without this cap, the sandbox inherits the Docker daemon default (`nofile` ~1048576). A runaway or hostile process can then open file descriptors until it exhausts them, causing a denial of service that can starve the gateway, the agent, or the host of file handles. If the entrypoint cannot set the limit (logs `[SECURITY] Could not set soft/hard nofile limit`), the container runs without a file-descriptor cap. For more information, refer to #4527.
Recommendation	Keep the default at 65536. If the agent legitimately keeps many connections or files open, raise it deliberately and monitor host file-descriptor usage. If the entrypoint logs a warning about ulimit restrictions, set the limit through the container runtime instead.

Non-Root User

The Hermes entrypoint, agent gateway, dashboard, and agent commands run as sandbox under OpenShell 0.0.116.

Aspect	Detail
Default	The OpenShell image entrypoint and workloads use `sandbox`.
What you can change	A direct container runtime outside OpenShell can override the image user; root mode can retain the separate gateway UID.
Risk if relaxed	Running dashboard or agent commands as `root` expands filesystem access and increases the impact of container escape vulnerabilities.
Recommendation	Keep the OpenShell image, dashboard, and agent commands under the `sandbox` user.

PATH Hardening

The entrypoint locks the PATH environment variable to system directories, preventing the agent from injecting malicious binaries into command resolution.

Aspect	Detail
Default	The default sandbox entrypoint sets `PATH` to `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` at startup. Agent-specific images may add locked read-only runtime directories, such as `/opt/venv/bin` for LangChain Deep Agents Code.
What you can change	This is not a user-facing knob. The entrypoint enforces it.
Risk if relaxed	Without PATH hardening, the agent could create an executable named `curl` or `git` in a writable directory earlier in the PATH, intercepting commands run by the entrypoint or other processes.
Recommendation	No action needed. The entrypoint handles this automatically.

Build Toolchain Removal

The Dockerfile removes compilers and network probes from the runtime image.

Aspect	Detail
Default	The Dockerfile purges `gcc`, `gcc-12`, `g++`, `g++-12`, `cpp`, `cpp-12`, `make`, `netcat-openbsd`, `netcat-traditional`, and `ncat` from the sandbox image.
What you can change	Modify the Dockerfile to keep these tools, or install them at runtime if package manager access is allowed.
Risk if relaxed	A compiler lets the agent build arbitrary native code, including kernel exploits or custom network tools. `netcat` enables arbitrary TCP connections that bypass HTTP-level policy enforcement.
Recommendation	Keep build tools removed. If the agent needs to compile code, run the build in a separate, purpose-built container and copy artifacts into the sandbox.

Image Digest Pinning

The managed blueprint references the sandbox image by an immutable @sha256: digest instead of a mutable tag such as :latest. A registry-side tag change cannot silently select another managed sandbox image.

Aspect	Detail
Default	NemoClaw selects the managed sandbox image by its digest.
What you can change	Use the onboarding `--from` path when you need to build from a reviewed custom image. Locally built custom images do not use the managed registry digest.
Risk if relaxed	Reverting to a mutable tag (`:latest`) allows a registry-side change to replace the sandbox image without any blueprint update, which is a supply-chain risk.
Recommendation	Keep the managed digest-pinned image unless you need a reviewed custom image. Pin the custom image’s base and dependencies before you build it.