Workspace and State Files

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

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:

/sandbox/.deepagents/.state/
/sandbox/.deepagents/skills/
/sandbox/.deepagents/agent/skills/

It also declares /sandbox/.deepagents/config.toml as a durable top-level state file because the file contains non-secret NemoClaw-generated provider and model configuration. 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 <name> download before destroying the sandbox.

Running nemo-deepagents <name> 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 /sandbox/.deepagents/config.toml can be overwritten by rebuilds because NemoClaw owns the managed inference route. Use nemo-deepagents <name> 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 <name> 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

• Backup and Restore workspace files explains snapshot and manual transfer workflows.
• Set Up MCP Servers explains the NemoClaw-managed MCP path for Deep Agents sandboxes.
• Deep Agents Code memory and skills explains upstream memory, AGENTS.md, and skill behavior.