> 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 full documentation content, see https://docs.nvidia.com/nemoclaw/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemoclaw/_mcp/server. # Workspace Files > What workspace personality and configuration files are, where they live, and how they persist across sandbox restarts. 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 | 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 — name, language, emoji, creature type. | | `AGENTS.md` | Behavioral rules, memory conventions, safety guidelines, and session workflow. | | `MEMORY.md` | Curated long-term memory distilled from daily notes. | | `memory/` | Directory of daily note files (`YYYY-MM-DD.md`) for session continuity. | ## Where They Live All workspace files reside inside the sandbox filesystem: ```text /sandbox/.openclaw/workspace/ ├── AGENTS.md ├── IDENTITY.md ├── MEMORY.md ├── SOUL.md ├── USER.md └── memory/ ├── 2026-03-18.md └── 2026-03-19.md ``` ## Multi-Agent Deployments A single NemoClaw sandbox can host more than one OpenClaw agent. When OpenClaw is configured with multiple named agents (e.g., a shared `main` agent plus per-user agents for a Teams-integrated deployment), each agent gets its own workspace directory alongside the default `workspace/`: ```text /sandbox/.openclaw/ ├── workspace/ # default agent (single-agent deployments) ├── workspace-main/ # named agent "main" ├── workspace-support/ # named agent "support" └── workspace-ops/ # named agent "ops" ``` Each per-agent workspace contains the same Markdown file structure as the default (`SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, `MEMORY.md`, `memory/`). Files are per-agent — changes in `workspace-main/AGENTS.md` are not visible to `workspace-support/`. Persistence and snapshots are handled automatically for per-agent workspaces: the sandbox entrypoint provisions each `workspace-/` directly under the writable `.openclaw/` tree so state survives sandbox restart, and `nemoclaw snapshot create` discovers every `workspace-/` directory and includes it in the snapshot bundle alongside the default `workspace/`. Files that operators typically want consistent across every agent workspace (`AGENTS.md`, shared skills, common templates) are not synced automatically. Each workspace is independent; changes in one don't propagate. Tracking shared-file tooling (shared mount, `workspaces list` command) in [#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). ## Persistence Behavior Workspace files live in the sandbox's persistent state volume, not in the container image. This means they survive normal container restarts, but they are deleted 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 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 destroy` deletes the sandbox and its persistent state volume. Workspace files are removed from the sandbox unless you created a snapshot or backup first. Back up your workspace files before running `nemoclaw destroy`. See [Backup and Restore](backup-restore) for instructions. ## Editing Workspace Files The agent reads these files at the start of every session. You can edit them in two ways: 1. Ask your agent to update its persona, memory, or user context. 2. Use `nemoclaw connect` to open a terminal inside the sandbox and edit files directly, or use `openshell sandbox upload` to push edited files from your host. ## Next Steps * [Set Up Task-Specific Sub-Agents](../inference/set-up-sub-agent) * [Backup and Restore workspace files](backup-restore) * [Commands reference](../reference/commands) Hermes stores durable agent state under `/sandbox/.hermes/` instead of the OpenClaw workspace directory. The main Hermes configuration lives in `/sandbox/.hermes/config.yaml`, environment settings live in `/sandbox/.hermes/.env`, and 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/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 only in the container image. Normal restarts preserve that state. Rebuilds and upgrades use NemoClaw's snapshot flow to preserve manifest-defined Hermes state, including `SOUL.md` and the SQLite database behind `.hermes/state.db`. 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 * [Backup and Restore workspace files](backup-restore) * [Commands reference](../reference/commands)