Skip to navigation
Manage SandboxesState and Backups

Understand Sandbox State

View as Markdown

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 ProviderHost PlatformStatus
DockerLinux or Windows Subsystem for Linux 2 (WSL2)Supported with a NemoClaw-managed Docker-driver gateway.
DockermacOS or native WindowsUnsupported.
KubernetesAny hostUnsupported because host directories are node-local and require separately qualified scheduling, policy, and security rules.
PodmanAny hostUnsupported because read-only host mounts have not passed runtime-provider qualification.
OpenShell MXCAny hostUnsupported 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:

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

nemo-deepagents <name> status

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

nemo-deepagents <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.

Deep Agents Code stores durable agent configuration, memory, skills, MCP state, and conversation state under its home directory. In a NemoClaw sandbox, dcode runs with HOME=/sandbox, so the upstream ~/.deepagents layout maps to /sandbox/.deepagents.

For upstream behavior, refer to the official Deep Agents Code pages for memory and skills, MCP tools, and Deep Agents Code overview.

Important Deep Agents State

Deep Agents Code normally creates the /sandbox/.deepagents/agent/ paths below when you start the first dcode session. nemoclaw <name> skill install can create /sandbox/.deepagents/agent/skills/ earlier.

PathPurpose
/sandbox/.deepagents/config.tomlNemoClaw-generated model and provider configuration for the selected OpenShell-managed inference path, including shared inference.local routes or the native NVIDIA provider.
/sandbox/.deepagents/.state/Deep Agents Code runtime state, including persisted session and MCP-related state.
/sandbox/.deepagents/agent/AGENTS.mdGlobal memory file for the default Deep Agents Code agent, loaded at session start.
/sandbox/.deepagents/agent/memories/Topic-specific markdown memories that Deep Agents Code can read and update across sessions.
/sandbox/.deepagents/skills/Legacy NemoClaw skill-upload state. Deep Agents Code does not load skills from this path, and nemo-deepagents <name> skill install leaves it untouched.
/sandbox/.deepagents/agent/skills/Canonical writable user-skill root declared by the Deep Agents Code integration. The agent owns discovery and activation; OpenShell preserves this agent state.
/sandbox/.deepagents/hooks.jsonUser-authored native hook configuration. It persists with the native home; review its executable commands before transferring it into another workspace.
/sandbox/.deepagents/.mcp.jsonAgent-native MCP configuration. NemoClaw-managed entries contain OpenShell credential placeholders and are read directly during status, migration, and rebuild. The file persists as part of the complete native home.
/sandbox/.deepagents/.state/auth.jsonUpstream auth state. The managed launchers refuse to start when this file contains credentials.
/sandbox/.deepagents/.state/chatgpt-auth.jsonUpstream ChatGPT auth state. The managed launchers refuse to start when this file exists.
/sandbox/.deepagents/.envUser-managed Deep Agents Code environment file. It persists as agent-written native-home state; do not place raw credentials here when an OpenShell credential binding is available.

Project-level Deep Agents files can also exist inside the working repository, such as .deepagents/AGENTS.md, .deepagents/skills/, and .deepagents/.mcp.json. Those files are ordinary project files. They persist when they live under your sandbox workspace because the entire native home/workspace is OpenShell-owned storage.

Persistence Behavior

Deep Agents state lives in the sandbox’s persistent state volume, not in the container image alone. Normal restarts preserve that state. Rebuilds and upgrades transfer the complete native home/workspace as one opaque archive. NemoClaw does not apply a Deep Agents path or config-key allowlist during that transfer, so unknown files, config.toml, hooks, skills, memories, histories, packages, and project state all move together. OpenShell-managed credential material remains under OpenShell ownership rather than entering the archive.

Managed MCP state is rebuilt from the agent-native file and current OpenShell policy, provider, and attachment state. NemoClaw keeps no host-side MCP desired state. Memory files such as /sandbox/.deepagents/agent/AGENTS.md and /sandbox/.deepagents/agent/memories/ are upstream Deep Agents Code files.

They transfer with the complete native home during rebuild. Copy them manually with nemo-deepagents <name> download before destroying the sandbox when you also need an independent backup.

Running nemo-deepagents <name> destroy clears the complete Deep Agents /sandbox persistence root before it asks OpenShell to delete the sandbox. If NemoClaw cannot prove that cleanup completed, it preserves the registry entry and stops before deletion so you can retry safely. Back up important Deep Agents state before destroying the sandbox.

Editing State

Prefer NemoClaw host commands for generated configuration such as model, provider, managed MCP, and policy settings. Direct edits to /sandbox/.deepagents/config.toml persist through rebuild. A later explicit configuration command can still change fields it owns.

Use nemo-deepagents <name> connect when you need to inspect runtime files interactively. Use nemo-deepagents <name> download for manual host downloads, or use openshell sandbox upload when you intentionally need the raw OpenShell upload path.

Use Deep Agents Code commands for upstream-managed memories and skills. For example, run dcode skills create <name> inside the sandbox to create a user skill, or use /remember inside an interactive dcode session to update memory.

OpenShell preserves the complete native home, but NemoClaw does not maintain a skill inventory or infer which skills are visible or active. Use nemo-deepagents <name> skill list for the selected agent’s native view.

Python Environment

Deep Agents Code runs from a NemoClaw-managed Python virtual environment at /opt/venv. The sandbox places /opt/venv/bin before system Python directories on PATH, so python3 and pip3 resolve to the managed environment by default.

NemoClaw keeps /opt/venv read-only to protect the pinned dcode harness. Create project-specific virtual environments under /sandbox when a task needs additional Python packages.

Next Steps