Understand Sandbox State | NVIDIA NemoClaw

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:

$ nemoclaw 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 nemoclaw <name> rebuild. If onboarding stops before sandbox creation, nemoclaw 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:

$ nemoclaw <name> status

The Host mounts section lists each source and target with (read-only). Connect to the sandbox:

$ nemoclaw <name> connect

At the sandbox prompt, inspect the mount options from the Linux mount table:

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

OpenClaw stores its personality, user context, and behavioral configuration in a set of Markdown files inside the sandbox. These files live at /sandbox/.openclaw/workspace/ and are collectively called workspace files.

File Reference

NemoClaw seeds the six template files below when the default workspace directory exists, is not a symbolic link, and is empty. Set NEMOCLAW_MINIMAL_BOOTSTRAP=1 before onboarding to skip default workspace template seeding.

File	Purpose
`SOUL.md`	Defines the agent’s persona, tone, and communication style.
`USER.md`	Stores information about the human the agent assists.
`IDENTITY.md`	Short identity card with name, language, emoji, and creature type.
`AGENTS.md`	Behavioral rules, memory conventions, safety guidelines, and session workflow.
`TOOLS.md`	Records workspace-specific tool guidance and operational notes.
`HEARTBEAT.md`	Defines recurring heartbeat checks when heartbeat processing is enabled.
`MEMORY.md`	Curated long-term memory distilled from daily notes. OpenClaw creates this file when it first stores long-term memory.
`memory/`	Directory of daily note files (`YYYY-MM-DD.md`) for session continuity. OpenClaw creates this directory when it first stores a daily note.

Where They Live

All workspace files reside inside the sandbox filesystem:

/sandbox/.openclaw/workspace/
├── AGENTS.md
├── HEARTBEAT.md
├── IDENTITY.md
├── MEMORY.md             # created on first long-term memory use
├── SOUL.md
├── TOOLS.md
├── USER.md
└── memory/               # created on first daily memory use
    ├── 2026-03-18.md
    └── 2026-03-19.md

Inside an OpenClaw sandbox, ~ expands to /sandbox, not to the OpenClaw workspace. Do not create workspace files as ~/USER.md or ~/SOUL.md. Those paths resolve to /sandbox/USER.md and /sandbox/SOUL.md, which are outside OpenClaw’s managed state and are not included in snapshots. Use $OPENCLAW_WORKSPACE_DIR/USER.md and $OPENCLAW_WORKSPACE_DIR/SOUL.md instead.

Multi-Agent Deployments

A single NemoClaw sandbox can host more than one OpenClaw agent. When you configure OpenClaw with multiple named agents, each agent gets its own workspace directory alongside the default workspace/. For example, a Teams-integrated deployment can use a shared main agent plus per-user agents.

/sandbox/.openclaw/
├── workspace/           # default agent (single-agent deployments)
├── workspace-main/      # named agent "main"
├── workspace-support/   # named agent "support"
└── workspace-ops/       # named agent "ops"

A named workspace does not receive the same seeded Markdown file structure as the default workspace: AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md, and HEARTBEAT.md. NemoClaw seeds these files only in the default workspace/. The sandbox entrypoint provisions each named workspace directory without copying the default templates into it. OpenClaw creates MEMORY.md and memory/ separately in each workspace when that agent first uses long-term or daily memory. Files are per-agent. Changes in workspace-main/AGENTS.md are not visible to workspace-support/.

NemoClaw handles persistence and snapshots automatically for per-agent workspaces. The sandbox entrypoint provisions each workspace-<name>/ directly under the writable .openclaw/ tree so state survives sandbox restart. nemoclaw <name> snapshot create discovers every workspace-<name>/ directory and includes it in the snapshot bundle alongside the default workspace/.

Files that operators typically want consistent across every agent workspace, such as AGENTS.md, shared skills, and common templates, are not synced automatically. Each workspace is independent, and changes in one do not propagate. NVIDIA tracks shared-file tooling (shared mount, workspaces list command) in #1260.

Persistence Behavior

Workspace files live in the sandbox’s persistent state volume, not in the container image. They survive normal container restarts, but NemoClaw deletes them when you destroy the sandbox.

Preserved During Restart, Rebuild, and Upgrade

Sandbox restarts preserve workspace files because the persistent state volume outlives individual container restarts.

The nemoclaw <name> rebuild command and the sandbox upgrade flow also preserve workspace state. Before replacing the container, NemoClaw snapshots the workspace state directories and restores them into the rebuilt sandbox.

If NemoClaw cannot archive any requested state file or directory, it reports the backup failure and stops before replacing the sandbox. It does not continue with a partial backup.

Deleted During Sandbox Destroy

Running nemoclaw <name> destroy deletes the sandbox and its persistent state volume. NemoClaw removes workspace files from the sandbox unless you created a snapshot or backup first.

Back up your workspace files before running nemoclaw <name> destroy. Refer to Create and Restore Snapshots for instructions.

Editing Workspace Files

The agent reads these files at the start of every session. You can edit them in two ways:

Ask your agent to update its persona, memory, or user context.
Use nemoclaw <name> connect to open a terminal inside the sandbox and edit files directly, or use openshell sandbox upload to push edited files from your host.