> 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 and state files are, where they live, and how they persist across sandbox restarts. 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](https://docs.langchain.com/oss/python/deepagents/code/memory-and-skills), [MCP tools](https://docs.langchain.com/oss/python/deepagents/code/mcp-tools), and [Deep Agents Code overview](https://docs.langchain.com/oss/python/deepagents/code/overview). ## Important Deep Agents State The `/sandbox/.deepagents/agent/` paths below do not exist immediately after onboarding. Deep Agents Code creates them when you start the first `dcode` session. | Path | Purpose | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `/sandbox/.deepagents/config.toml` | NemoClaw-generated model and provider configuration for the managed `inference.local` route. | | `/sandbox/.deepagents/.state/` | Deep Agents Code runtime state, including persisted session and MCP-related state. | | `/sandbox/.deepagents/agent/AGENTS.md` | Global 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/` | User-level skills available to Deep Agents Code in the sandbox. | | `/sandbox/.deepagents/agent/skills/` | Default-agent skills created by the built-in skill creator and preserved by NemoClaw snapshots. | | `/sandbox/.deepagents/.nemoclaw-mcp.json` | NemoClaw-generated managed MCP projection with OpenShell credential placeholders. NemoClaw reconstructs it from host-side registry state. | | `/sandbox/.deepagents/.state/auth.json` | Upstream auth state. The managed launchers refuse to start when this file contains credentials. | | `/sandbox/.deepagents/.state/chatgpt-auth.json` | Upstream ChatGPT auth state. The managed launchers refuse to start when this file exists. | | `/sandbox/.deepagents/.env` | User-managed Deep Agents Code environment file. NemoClaw treats it as credential-bearing and does not snapshot it. | | `/sandbox/.deepagents/.mcp.json` | User-authored Deep Agents Code MCP config. NemoClaw treats it as credential-bearing and does not snapshot it. | 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, but NemoClaw's Deep Agents manifest only declares `/sandbox/.deepagents` state for the managed agent home. ## 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 use NemoClaw's snapshot flow to preserve the manifest-defined Deep Agents state tree. The Deep Agents manifest declares these durable directories: ```text /sandbox/.deepagents/.state/ /sandbox/.deepagents/skills/ /sandbox/.deepagents/agent/skills/ ``` It also declares `/sandbox/.deepagents/config.toml` as a durable top-level state file with key-level ownership. The target sandbox's current Deep Agents manifest defines this ownership policy, so a snapshot cannot weaken it. NemoClaw keeps the newly generated inference route headers and the `models` and `update` tables authoritative during rebuild. On a NemoClaw-managed image, only the allowlisted `ui.show_scrollbar`, `ui.show_url_open_toast`, `threads.relative_time`, and `threads.sort_order` preferences can be restored from the previous file. Runtime-controlled, unknown, executable, and security-sensitive backup keys are dropped on that managed path. A Deep Agents target created from a custom Dockerfile restores `config.toml` as a whole file because the custom image owns its config schema. On the managed key-level restore path, if config validation or safe atomic replacement fails, NemoClaw marks the restore as failed instead of falling back to a whole-file copy. Credential-bearing files such as `.deepagents/.env` and user-authored `.deepagents/.mcp.json` are intentionally omitted from snapshots. Managed MCP state is rebuilt from the host-side NemoClaw registry and OpenShell provider state instead of treated as user-authored durable state. Memory files such as `/sandbox/.deepagents/agent/AGENTS.md` and `/sandbox/.deepagents/agent/memories/` are upstream Deep Agents Code files. If you rely on them before they are manifest-backed in your release, copy them manually with `nemo-deepagents download` before destroying the sandbox. Running `nemo-deepagents destroy` deletes the sandbox and its persistent state volume. 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 NemoClaw-owned or non-allowlisted keys in `/sandbox/.deepagents/config.toml` can be overwritten by rebuilds. Use `nemo-deepagents connect` when you need to inspect runtime files interactively, or use `openshell sandbox download` and `openshell sandbox upload` for manual file transfer. Use Deep Agents Code commands for upstream-managed memories and skills. For example, run `dcode skills create ` inside the sandbox to create a user skill, or use `/remember` inside an interactive `dcode` session to update memory. NemoClaw preserves the manifest-declared skills and state directories, but it does not inspect or validate the content of user-authored memory and skill files beyond the snapshot safety checks. ## 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 * [Create and Restore Snapshots](create-and-restore-snapshots) explains the managed snapshot workflow. * [Add an MCP Server](../mcp-servers/add-an-mcp-server) explains the NemoClaw-managed MCP path for Deep Agents sandboxes. * [Deep Agents Code memory and skills](https://docs.langchain.com/oss/python/deepagents/code/memory-and-skills) explains upstream memory, `AGENTS.md`, and skill behavior.