Understand Filesystem Controls

NemoClaw restricts which paths the agent can read and write, protecting system binaries, configuration files, and gateway credentials.

OpenShell covers additional filesystem enforcement details, including hard_requirement compatibility mode for Landlock and policy path validation rules. Refer to the Filesystem Controls section of the OpenShell Security Best Practices.

Read-Only System Paths

The container mounts system directories read-only to prevent the agent from modifying binaries, libraries, or configuration files.

Aspect	Detail
Default	`/usr`, `/lib`, `/proc`, `/dev/urandom`, `/app`, `/etc`, `/var/log`, and `/var/lib/dpkg` are read-only.
What you can change	Add or remove paths in the `filesystem_policy.read_only` section of the policy file.
Risk if relaxed	Making `/usr` or `/lib` writable lets the agent replace system binaries (such as `curl` or `node`) with trojanized versions. Making `/etc` writable lets the agent modify DNS resolution, TLS trust stores, or user accounts.
Recommendation	Never make system paths writable. If the agent needs a writable location for generated files, use a subdirectory of `/sandbox`.

Agent Config Directory

The /sandbox/.openclaw directory contains the OpenClaw gateway configuration (model routing, CORS settings, channel config). The current entrypoint reads the gateway auth token from OpenClaw config when present, exports it as OPENCLAW_GATEWAY_TOKEN, and writes it to /tmp/nemoclaw-proxy-env.sh so interactive sandbox sessions can reach the gateway through system-wide shell hooks.

In root mode, the gateway process still runs as the separate gateway user, but the token is intentionally available to sandbox shells for local gateway access.

Writable agent state such as plugins, skills, hooks, and workspace metadata lives directly under /sandbox/.openclaw.

By default, this directory starts writable so the agent can manage its own config, install skills, and write to standard home-directory paths natively. For sensitive workloads, use a reviewed host-side immutability workflow after initial setup so the sandbox user cannot change config or high-risk state entry points.

The immutability workflow derives its path plan from the selected agent manifest. For OpenClaw, it locks agents, canvas, cron, devices, extensions, hooks, memory, plugins, profiles, skills, telegram, wechat, whatsapp, workspace, and workspace-* directories to root:sandbox and removes group and world write access.

The root-only helper traverses from opened directory descriptors with no-follow semantics instead of using recursive pathname chown or chmod. Read-only preflight and unlock operations reject unsafe external symlinks, hardlinks, special files, cross-device entries, and entries that race the traversal without modifying them.

After the top-level config binding is frozen, lockdown makes containment monotonic. It removes unsafe symlinks, special entries, and protected-root names that are not directories through descriptor-relative operations without following their targets.

For protected regular files, lockdown publishes a fresh inode, severing hardlinks while preserving file content, read/execute mode, timestamps, and supported extended attributes; this also revokes write authority held through a descriptor opened before shields up.

The OpenClaw gateway (a member of the sandbox group) keeps read access to plugin and agent code; the sandbox user can no longer write them.

The same workflow locks the secret-bearing credentials and identity directories. The guard sets each confidentiality root to root:sandbox 0710, including a non-empty credentials directory. It sets every nested directory and file to root:root and removes all group and world permission bits.

The sandbox group cannot list, create, or remove entries in a confidentiality root, and neither the sandbox user nor gateway can read stored secrets. They can inspect metadata for a direct child only when they already know its name. Probing a missing direct child, such as the legacy credentials/oauth.json, returns ENOENT instead of EACCES.

Restoring the mutable-default posture returns those directories to sandbox:sandbox 2770.

For plan-aware current images and host-injected transitions, each agent manifest declares only its own protected paths, confidential paths, dynamic prefixes, and writable subpaths. The lock helper applies only that selected manifest plan and skips declared paths that are not present.

Historical OpenClaw and Hermes images that have a bundled helper but no generated plan use the helper’s reviewed legacy inventory until the sandbox is rebuilt. State directories without a Shields declaration remain mutable.

Inside a locked tree, the helper keeps each agents/<agent-id>/sessions/ root at sandbox:sandbox 2770 so the OpenClaw TUI can create and write session metadata under an otherwise root-owned parent. After containment, when an agent directory has no sessions entry, lockdown creates that carve-out root.

An agent booting for the first time under an active lock can then write sessions. It validates the carve-out root but deliberately does not traverse or rewrite live session descendants.

Cross-device entries, detected traversal races, or failures to remove or replace an unsafe entry make lockdown fail closed with the exact path and reason.

DAC permissions (default). The sandbox user owns /sandbox/.openclaw with mode 2770 (setgid sandbox:sandbox) and openclaw.json with mode 660, so the agent and its group can read and write config directly. A reviewed host-side immutability workflow should compare the intended ownership and mode with the live sandbox filesystem before treating the config tree as locked.
Config integrity hash. The image includes a SHA256 hash of openclaw.json. In the default mutable state, .config-hash is sandbox-owned and is not a tamper-proof trust anchor, so startup does not fail closed on that hash. When the hash is root-owned and read-only, startup enforces it and refuses to start if the hash does not match.
Content integrity seal. A clean immutable config lock can capture a SHA-256 seal of openclaw.json and other locked files into host-side state. Verification recomputes hashes inside the sandbox and surfaces drift on mismatch, so a host-root tamper that flips permissions back to 444 root:root after rewriting the file is still flagged. Sandboxes locked before the seal landed have no recorded hash; permission-only verification cannot prove their bytes match the image original, so the seal is not a retroactive proof of integrity for legacy state. The same limitation applies when the locked file set grew after the existing seal was captured. Rebuild the sandbox for a known-good baseline before trusting a new seal.
Gateway token environment. The gateway exports OPENCLAW_GATEWAY_TOKEN and writes it to /tmp/nemoclaw-proxy-env.sh for interactive sandbox sessions. Keep this in mind when deciding whether a workload should run with mutable config or an immutable config posture.

Aspect	Detail
Default	The sandbox keeps `/sandbox/.openclaw` writable (`2770 sandbox:sandbox`), sets `openclaw.json` to `660 sandbox:sandbox`, lets the agent manage state directly, and has the gateway place `OPENCLAW_GATEWAY_TOKEN` in `/tmp/nemoclaw-proxy-env.sh` for interactive shells.
What you can change	Apply a reviewed host-side immutability workflow to lock config and state directories with DAC permissions and the immutable flag where available.
Risk of default	A writable `.openclaw` directory lets the agent modify its own gateway config: disabling CORS or redirecting inference to an attacker-controlled endpoint.
Recommendation	For always-on assistants handling sensitive workloads, lock config after initial setup. For development workflows, the writable default is appropriate.

Writable Paths

The agent has read-write access to /sandbox, /tmp, /dev/null, and /dev/pts.

Aspect	Detail
Default	`/sandbox` (agent workspace), `/tmp` (temporary files), `/dev/null`, and `/dev/pts` (the devpts pseudo-terminal directory, required so PTY-based tools such as `tmux`, `script`, and interactive shells can allocate a terminal).
What you can change	Add additional writable paths in `filesystem_policy.read_write`.
Risk if relaxed	Each additional writable path expands the agent’s ability to persist data and potentially modify system behavior. Adding `/var` lets the agent write to log directories. Adding `/home` gives access to other user directories.
Recommendation	Keep writable paths to `/sandbox` and `/tmp`. If the agent needs a persistent working directory, create a subdirectory under `/sandbox`.

Landlock LSM Enforcement

Landlock is a Linux Security Module that enforces filesystem access rules at the kernel level.

Aspect	Detail
Default	`compatibility: best_effort`. The entrypoint applies Landlock rules when the kernel supports them and silently skips them on older kernels.
What you can change	This is a NemoClaw default, not a user-facing knob.
Risk if relaxed	On kernels without Landlock support (pre-5.13), filesystem restrictions rely solely on container mount configuration, which is less granular.
Recommendation	Run on a kernel that supports Landlock (5.13+). Ubuntu 22.04 LTS and later include Landlock support.