> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemoclaw/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemoclaw/_mcp/server. # Understand Sandbox State > What agent workspace, sandbox state, and read-only host mounts are, where they live, and how they persist. NemoClaw sandboxes keep agent workspace and state files across ordinary restarts. You can also expose selected host directories for live, read-only access when copying files into the sandbox is not appropriate. ## Mount a Host Directory for Read-Only Access Onboarding can expose an existing host directory inside a sandbox when the selected runtime provider and host platform support read-only host mounts. The same command works with OpenClaw, Hermes, and LangChain Deep Agents Code sandboxes. ### Runtime Support The runtime provider and host platform determine whether NemoClaw can create the mount: | Runtime Provider | Host Platform | Status | | ---------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Docker | Linux or Windows Subsystem for Linux 2 (WSL2) | Supported with a NemoClaw-managed Docker-driver gateway. | | Docker | macOS or native Windows | Unsupported. | | Kubernetes | Any host | Unsupported because host directories are node-local and require separately qualified scheduling, policy, and security rules. | | Podman | Any host | Unsupported because read-only host mounts have not passed runtime-provider qualification. | | OpenShell MXC | Any host | Unsupported because OpenShell MXC does not expose a qualified native host-sharing contract. | When you request `--host-mount`, NemoClaw checks the selected runtime provider and host platform before it records onboarding state or changes runtime resources. NemoClaw reports the reason that the unsupported provider declares. For a supported provider on an unqualified host, NemoClaw reports that the host platform is not qualified. NemoClaw does not fall back to Docker bind-mount configuration. A runtime-provider implementation must meet these requirements before it can declare support: * Declare qualified host platforms when supported, or declare an explicit reason when unsupported. * Preserve the source, target, symbolic-link, duplication, and read-only validation described on this page. * Revalidate the source path identity immediately before sandbox creation. * Implement provider-specific create configuration and host-side activation without a Docker fallback. * Test requested and persisted mounts across onboarding, resume, rebuild, and failure paths. The mount crosses the sandbox boundary and gives every sandbox process read access to the complete host directory tree. Read-only access prevents sandbox writes, but it does not protect confidential host files from being read. Do not mount a directory that contains credentials, private keys, or other files the agent must not read. Before onboarding, confirm that each source is an existing absolute host directory with no symbolic link in any path component. Choose a normalized absolute target strictly below `/sandbox`, such as `/sandbox/project`. Repeat `--host-mount` to expose more than one directory: ```bash nemohermes onboard \ --host-mount /home/user/project:/sandbox/project \ --host-mount /home/user/reference:/sandbox/reference ``` Onboarding rejects relative paths, missing source directories, symbolic link path components, targets outside `/sandbox`, duplicate sources, and duplicate targets. NemoClaw rejects a mount declaration that contains control characters, Unicode formatting controls, or Unicode line and paragraph separators. This validation happens before onboarding or a diagnostic report displays either path. Every accepted host mount is read-only, and the command does not provide a read-write option. The sandbox reads the live host directory instead of a copied snapshot. Host-side file changes remain visible inside the sandbox while the mount exists. Onboarding enables the OpenShell Docker bind-mount capability only when a requested or registered host mount requires it. NemoClaw stores accepted mount declarations in the sandbox registry and reuses them during `nemohermes rebuild`. If onboarding stops before sandbox creation, `nemohermes onboard --resume` reuses the recorded declarations. Destroying the sandbox removes its registry entry and the corresponding mount declaration, but it does not delete host files. After onboarding, inspect the registered host mounts: ```bash nemohermes status ``` The `Host mounts` section lists each source and target with `(read-only)`. Connect to the sandbox: ```bash nemohermes connect ``` At the sandbox prompt, inspect the mount options from the Linux mount table: ```bash awk '$2 == "/sandbox/project" { print $2, $4 }' /proc/mounts ``` The mount is active when the output includes `/sandbox/project` and the `ro` option. Read a known file under `/sandbox/project` to confirm that the expected host directory is visible. Hermes stores durable agent state under `/sandbox/.hermes/`, not in the OpenClaw workspace directory. The main Hermes configuration lives in `/sandbox/.hermes/config.yaml`. Environment settings live in `/sandbox/.hermes/.env`. Runtime state, such as logs, memory, platform sessions, and the SQLite state database, lives under the same `.hermes` tree. ## Important Hermes State | Path | Purpose | | ------------------------------------------- | ------------------------------------------------------------------------------------------ | | `/sandbox/.hermes/config.yaml` | NemoClaw-generated Hermes runtime configuration. | | `/sandbox/.hermes/.env` | NemoClaw-generated environment and messaging placeholders. | | `/sandbox/.hermes/state.db` | Hermes SQLite state database. | | `/sandbox/.hermes/kanban.db` | Default Hermes kanban board database. NemoClaw snapshots preserve only this default board. | | `/sandbox/.hermes/profiles/dashboard-home/` | Hermes Web Dashboard profile, including `MEMORY.md` and `USER.md`. | | `/sandbox/.hermes/platforms/` | Messaging platform state, including QR-paired sessions such as WhatsApp. | | `/sandbox/.hermes/logs/` | Hermes runtime logs. | | `/sandbox/SOUL.md` | Durable top-level Hermes persona file preserved by NemoClaw snapshots. | ## Persistence Behavior Hermes state lives in the sandbox's persistent state volume, not in the container image alone. Normal restarts preserve that state. Rebuilds and upgrades use NemoClaw's snapshot flow to preserve manifest-defined Hermes state, including `SOUL.md`, the Web Dashboard profile under `.hermes/profiles/dashboard-home/`, the SQLite database behind `.hermes/state.db`, and the default kanban board in `.hermes/kanban.db`. Named boards, attachments, worker logs, scratch workspaces under `.hermes/kanban/`, and external directory or worktree targets are not included in the kanban backup. Running `nemohermes destroy` deletes the sandbox and its persistent state volume. Back up important state before destroying a Hermes sandbox. ## Editing State Prefer NemoClaw host commands for generated configuration such as model, provider, messaging, and policy settings. Direct edits to `/sandbox/.hermes/config.yaml` or `/sandbox/.hermes/.env` can be overwritten by rebuilds. Use `nemohermes connect` when you need to inspect runtime files interactively, or use `openshell sandbox download` and `openshell sandbox upload` for manual file transfer. ## Next Steps * [Create and Restore Snapshots](create-and-restore-snapshots) * [Commands reference](../../reference/commands)