diff --git a/docs/index.yml b/docs/index.yml index 4df68ed4499..382e015785d 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -162,6 +162,9 @@ navigation: - page: "Architecture Details" path: _build/agent-variants/reference/architecture.openclaw.generated.mdx slug: architecture + - page: "Host Files and State" + path: reference/host-files-and-state.mdx + slug: host-files-and-state - page: "CLI Commands Reference" path: _build/agent-variants/reference/commands.openclaw.generated.mdx slug: commands @@ -314,6 +317,9 @@ navigation: - page: "Architecture Details" path: _build/agent-variants/reference/architecture.hermes.generated.mdx slug: architecture + - page: "Host Files and State" + path: reference/host-files-and-state.mdx + slug: host-files-and-state - page: "CLI Commands Reference" path: reference/commands-nemohermes.mdx slug: commands diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx index 814c2a64a10..60b66005fc6 100644 --- a/docs/manage-sandboxes/lifecycle.mdx +++ b/docs/manage-sandboxes/lifecycle.mdx @@ -309,6 +309,7 @@ For non-interactive runs (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or a non-TTY sh `--yes` stays non-destructive by design. It only acknowledges the global confirmation prompt and never purges preserved user data on its own. Full purge always requires an explicit `--destroy-user-data` or the matching env var, so existing automation using `--yes` retains its safe behaviour. +Refer to [Host Files and State](../reference/host-files-and-state) for the full `~/.nemoclaw/` file and directory reference. Refer to the [Commands reference](../reference/commands#$$nemoclaw-uninstall) for the full preservation contract. diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index 3d54a051797..b011788f051 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -8,18 +8,39 @@ description-agent: "Includes the full CLI reference for standalone NemoHermes co keywords: ["nemohermes cli commands", "hermes command reference", "nemohermes command reference"] content: type: "reference" -exclude-from-skills-gen: true --- {/* This file is generated from docs/reference/commands.mdx by scripts/sync-agent-variant-docs.ts. Run `npm run docs:sync-agent-variants` to regenerate it. Do not edit by hand. */} +import { AgentOnly } from "../_components/AgentGuide"; + + + +The `nemohermes` CLI is the primary interface for managing NemoClaw sandboxes. +It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`). +For guidance on when to use `nemohermes` versus the underlying `openshell` CLI, refer to [CLI Selection Guide](cli-selection-guide). + + + + The `nemohermes` alias is the primary interface for managing Hermes sandboxes through NemoClaw. It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes bash`). Most commands in this reference use the same arguments and subcommands across agent variants. Use `nemohermes` when you want Hermes selected by default. For guidance on choosing between the agent CLIs and the underlying `openshell` CLI, refer to [CLI Selection Guide](cli-selection-guide). + + ## Agent Selection + + +Use `nemohermes` for the OpenClaw variant. +OpenClaw is the default agent for `nemohermes onboard` unless you pass `--agent hermes` or set `NEMOCLAW_AGENT=hermes`. +OpenClaw-specific sections below describe the `/nemoclaw` slash command, the OpenClaw dashboard URL, the OpenClaw gateway token, and OpenClaw config paths under `/sandbox/.openclaw`. + + + + Use `nemohermes` for the Hermes variant. It selects Hermes by default during onboarding and for other commands. Use `--agent hermes` during onboarding or set `NEMOCLAW_AGENT=hermes` when you need the same selection through another entry point. @@ -30,12 +51,33 @@ nemohermes onboard # selects Hermes by default nemohermes my-sandbox connect # connects to a Hermes sandbox ``` + + ## In-Sandbox Commands + + +The `/nemoclaw` slash command is available inside the OpenClaw chat interface for quick actions: + +| Subcommand | Description | +|---|---| +| `/nemoclaw` | Show slash-command help and host CLI pointers | +| `/nemoclaw status` | Show sandbox and inference state | +| `/nemoclaw shields [status]` | Explain that shields status is unavailable inside the sandbox and point to `nemohermes shields status` on the host | +| `/nemoclaw onboard` | Show onboarding status and reconfiguration guidance | +| `/nemoclaw eject` | Show rollback instructions for returning to the host installation | + +Use host-side `nemohermes shields status|up|down` commands to inspect or change shields posture. + + + + Hermes does not use the OpenClaw chat slash command. Use the host-side `nemohermes` commands for lifecycle, status, policy, and inference operations. The in-sandbox Hermes integration installs the NemoClaw Hermes plugin, which exposes tools for status, environment information, and skill reload support, plus an `on_session_start` hook. + + ## Standalone Host Commands The CLI handles host-side operations that run outside the selected agent runtime. @@ -96,6 +138,8 @@ Use this command for new installs and for recreating a sandbox after changes to nemohermes onboard [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from ] [--name ] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device ] [--agent ] [--agents ] [--control-ui-port ] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software] ``` + + For Hermes, use the alias or pass the agent explicitly: ```bash @@ -103,6 +147,8 @@ nemohermes onboard [options] nemoclaw onboard --agent hermes [options] ``` + + `--agent` accepts the canonical manifest names from `nemohermes agents list` plus common aliases. For example, `nemohermes` resolves to `hermes`, while `dcode`, `deepagents`, `deepagents-code`, and `langchain` resolve to `langchain-deepagents-code`. @@ -176,14 +222,25 @@ Onboarding removes any preset that is not in the list. `skip` leaves the applied set untouched and does not apply tier defaults. NemoClaw filters tier suggestions and resume selections by active agent support, so unsupported presets such as Brave Search are not reapplied to agents that do not support them. + + Hermes managed-tool gateway selections add matching Hermes-specific policy presets, such as `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`, without applying unsupported OpenClaw-only presets. + + | Value | Behaviour | |-------|-----------| | `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`. | | `custom` | Apply exactly `NEMOCLAW_POLICY_PRESETS`. Previously-applied presets not in the list are removed. Alias: `list`. | | `skip` | Skip the policy step entirely. Aliases: `none`, `no`. | + + +If you enable Brave Search during onboarding, NemoClaw registers a Brave Search OpenShell provider and keeps `openclaw.json` on an OpenShell credential placeholder. +At egress, OpenShell rewrites Brave's `X-Subscription-Token` header with the real `BRAVE_API_KEY`. +Treat Brave Search as an explicit opt-in and use a dedicated low-privilege Brave key. + + For non-interactive onboarding, you must explicitly accept the third-party software notice: ```bash @@ -204,10 +261,29 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOC If the installer cannot prompt for the notice in a terminal and no explicit acceptance is set, it exits before installing Node.js or the NemoClaw CLI. + + +To enable Brave Search in non-interactive mode, set: + +```bash +BRAVE_API_KEY=... \ + nemohermes onboard --non-interactive +``` + +`BRAVE_API_KEY` enables Brave Search in non-interactive mode and also enables `web_fetch`. +If Brave Search key validation fails in non-interactive mode, onboarding prints a warning, skips web search setup, and continues with the rest of the sandbox setup. +After fixing the key, rerun onboarding with `BRAVE_API_KEY` set so NemoClaw can validate the key, register the Brave Search provider, and apply the `brave` policy preset. +If the sandbox already exists without web search, accept the recreate prompt or pass `--recreate-sandbox`. + + + + Hermes does not use NemoClaw's OpenClaw Brave Search setup. If you authenticate Hermes through Nous Portal OAuth, the wizard can prompt for managed Nous tool gateways such as web search. API-key mode is inference-only and does not enable managed tool gateways. + + The wizard prompts for a sandbox name. Names must be 1 to 63 characters, lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number. The CLI rejects names that do not match these rules. @@ -216,12 +292,23 @@ Names that match global CLI commands (`status`, `list`, `debug`, etc.) are rejec Use `--agent ` to target a specific installed agent profile during onboarding. The `nemohermes onboard --help` output lists installed runtime names inline, and `nemohermes agents list` shows the same runtimes with manifest descriptions. + + +Use `--agents ` to declare secondary OpenClaw agents, `agents.defaults`, and main-agent overrides in a checked-in manifest that NemoClaw bakes into the sandbox image at build time. +Refer to [Declarative Multi-Agent Manifest](../inference/declarative-agents-manifest) for the schema and OpenClaw-native sub-agent field semantics. + + + Use `--control-ui-port ` to choose the host dashboard port for a sandbox. The value must be an integer from `1024` through `65535`. This flag takes precedence over `CHAT_UI_URL`, `NEMOCLAW_DASHBOARD_PORT`, the previous registry value, and the default port. + + For Hermes sandboxes, do not use port `8642`; NemoClaw reserves it for the Hermes OpenAI-compatible API and rejects it as a dashboard port before sandbox creation. + + If you enable Slack during onboarding, the wizard collects both the Bot Token (`SLACK_BOT_TOKEN`) and the App-Level Token (`SLACK_APP_TOKEN`). Socket Mode requires both tokens. The app-level token is stored in a dedicated `slack-app` OpenShell provider and forwarded to the sandbox alongside the bot token. @@ -255,8 +342,17 @@ NemoClaw aborts the recreate when the backup cannot complete in full, including Set `NEMOCLAW_RECREATE_WITHOUT_BACKUP=1` to skip the pre-recreate backup. The destination sandbox starts with a fresh workspace. + + +For OpenClaw, the backed-up paths include agents, extensions, workspace, skills, hooks, identity, devices, canvas, cron, memory, telegram, wechat, credentials, and `/sandbox/.openclaw/workspace/`. + + + + For Hermes, the backed-up paths come from `agents/hermes/manifest.yaml`, including `/sandbox/.hermes` state such as memories, sessions, skills, plugins, cron, logs, plans, workspace, messaging platform state, and `runtime/state.db`. + + Before creating the gateway, the wizard runs preflight checks. It verifies that Docker is reachable, warns on untested runtimes such as Podman, and prints host remediation guidance when prerequisites are missing. The preflight also enforces the OpenShell version range declared in the blueprint (`min_openshell_version` and `max_openshell_version`). @@ -459,6 +555,18 @@ Run a single command non-interactively in a running sandbox via the OpenShell ex The command runs as the sandbox user with `HOME=/sandbox`, so in-sandbox tooling resolves NemoClaw-provisioned config the same way it does for `connect` and `openshell sandbox connect`. This is the supported substitute for `docker exec` on the sandbox container; raw `docker exec` runs as root and lands on `HOME=/root`, where the selected agent config is not present. + + +OpenClaw config resolves under `/sandbox/.openclaw`. + +```bash +nemohermes my-assistant exec -- openclaw agent -m "What is 2+2?" +nemohermes my-assistant exec --workdir /sandbox/workspace -- ls -la +``` + + + + Hermes config resolves under `/sandbox/.hermes`. ```bash @@ -466,10 +574,24 @@ nemohermes my-assistant exec -- hermes --version nemohermes my-assistant exec --workdir /sandbox/workspace -- ls -la ``` + + Everything after `--` is forwarded verbatim to the sandbox command, including flags the inner command needs. + + +After an OpenClaw one-shot command exits, NemoClaw verifies and, when needed, restores the mutable config permission contract. +When cleanup succeeds, `exec` returns the remote command's exit code. +If cleanup cannot inspect, restore, or verify that contract, it fails closed and prints `OpenClaw permission cleanup failed (...)` to `stderr`. +In that case, `exec` returns the cleanup failure instead of the remote command's status. + + + + The exit code is the remote command's exit code. + + The OpenShell exec endpoint rejects any command argument (the values after `--`) that contains a newline or carriage return, so multi-line commands such as a `bash` heredoc cannot be passed through `exec`. NemoClaw detects this before dispatch, names the offending argument position, and exits with status `2` instead of surfacing the lower-level OpenShell `InvalidArgument` error. Join the statements with semicolons (`nemohermes exec -- bash -lc "cmd1; cmd2"`). @@ -484,6 +606,51 @@ Or write the script to a file in the sandbox and run it (`nemohermes exec ### `nemohermes agent` + + +Run one agent turn non-interactively in a running sandbox. +For OpenClaw sandboxes, this command forwards arguments to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. +For terminal-runtime sandboxes, NemoClaw forwards arguments to the manifest-declared interactive command; LangChain Deep Agents Code sandboxes run `dcode ...`. +Use this when driving the sandbox programmatically from another process (CI job, multi-agent platform, evaluation harness) rather than from an interactive terminal. + +All flags accepted by the selected in-sandbox agent CLI are forwarded verbatim, so the upstream surface stays the single source of truth. + +OpenClaw invocations must include at least one target selector: `--agent`, `--session-id`, `--session-key`, or `--to`. +This keeps the wrapper from falling back to the unspecified default-session behaviour. +Conflict resolution between multiple selectors is delegated to the in-sandbox `openclaw agent` argv contract; the host-side guard only checks presence. + +```bash +nemohermes my-assistant agent --agent work -m "Summarise README.md" +nemohermes my-assistant agent --agent work -m "Status update?" +nemohermes my-assistant agent --session-id review-42 -m "Any new findings?" +nemohermes my-assistant agent --session-key intake-42 --json -m 'ping' +nemohermes dcode-sandbox agent --help +nemohermes dcode-sandbox agent -n "Summarize this repository" +``` + +When post-command permission cleanup succeeds, the wrapper inherits the remote command's exit code so host-side pipelines can branch on it. +If cleanup fails closed, the wrapper prints the command and cleanup statuses to `stderr` and returns the cleanup failure. +For normal turns, streaming forwards whatever the in-sandbox agent command emits on `stdout`; the wrapper adds no buffering. +When the top-level OpenClaw `--json` output flag is present, the wrapper uses a captured no-TTY path with a `64 MiB` buffer so `stdout` stays parseable JSON. +Raw `stderr` is forwarded, and failed-tool or untrusted-child provenance found in the stdout JSON is appended to `stderr`. +Literal `--json` values consumed by flags such as `-m` or `--reply-channel`, or arguments after `--`, stay on the normal passthrough path. +Documented value flags written as `--flag=value`, such as `--session-id=s1`, are recognized the same way as separated value flags. +If an unrecognized OpenClaw option appears before `--json`, NemoClaw also keeps the command on the normal passthrough path so OpenClaw remains the argv source of truth. + +Common OpenClaw flags include `-m `, `--session-id `, `--agent `, `--model `, `--thinking `, `--json`, `--deliver`, `--reply-channel `, and `--timeout `. +For OpenClaw sandboxes and registry fallbacks, `nemohermes agent --help` prints the wrapper-level summary locally. +Invoke `nemohermes exec -- openclaw agent --help` to view the upstream OpenClaw help text directly. +For registered terminal-runtime sandboxes, bare invocations and `--help` are forwarded to the terminal command, so a LangChain Deep Agents Code sandbox receives `dcode` for `nemohermes agent` and `dcode --help` for `nemohermes agent --help`. + +Host-side validation runs before the sandbox dispatch: + +- OpenClaw sandboxes and registry fallbacks must include at least one target selector flag: `--agent`, `--session-id`, `--session-key`, or `--to` in either `--flag value` or `--flag=value` form. OpenClaw invocations without a selector exit `2` and print `No target session selected` locally, without paying the in-sandbox dispatch cost. Registered terminal-runtime sandboxes delegate bare invocations and help flags to the manifest command instead. +- If the sandbox is registered but not in a `Ready` or `Running` phase, the wrapper exits `1` and prints the documented recovery commands (`nemohermes recover`, `nemohermes rebuild --yes`, `nemohermes onboard --resume`) rather than deferring the readiness rejection to `openshell sandbox exec`. +- If a recent timed shields window auto-restored before the one-shot OpenClaw command, the wrapper prints a stderr-only reminder such as `Shields auto-relocked` with the matching `nemohermes shields down --timeout ...` command before dispatch. JSON stdout stays parseable, and the warning is advisory because current scope state still belongs to OpenClaw and OpenShell. + + + + The `agent` wrapper rejects Hermes sandboxes with guidance for the Hermes HTTP API. Hermes sandboxes expose an OpenAI-compatible API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. @@ -496,6 +663,8 @@ curl -sN http://127.0.0.1:8642/v1/chat/completions \ -d '{"model":"","messages":[{"role":"user","content":"What is 2+2?"}],"stream":true}' ``` + + ### Advanced Sandbox Maintenance Commands The following commands are available for targeted host-side maintenance, but they are not part of the top-level public command list. @@ -561,6 +730,8 @@ Use [`nemohermes gateway restart`](#nemohermes-name-gateway-restart) when nemohermes my-assistant recover ``` + + `recover` re-evaluates the documented Hermes secret boundary against `/sandbox/.hermes/.env` and the supervisor runtime environment on every run, including when the gateway is already healthy. If the file contains raw secret-shaped values (for example a pasted Telegram, Discord, or Slack bot token in place of the expected `openshell:resolve:env:` placeholder), the command exits non-zero and prints the offending key. The direct root-entrypoint supervisor stops a running gateway after this refusal, while the managed controller refuses before signaling the observed child. @@ -571,6 +742,8 @@ Mutable config under the managed topology has no durable root-owned hash anchor If the boundary validator or supervisor helper is missing, recovery fails closed, names the sandbox, explains that `/sandbox/.hermes/.env` could not be re-evaluated, and leaves an otherwise healthy gateway untouched. Rebuild an older sandbox image with `nemohermes rebuild --yes` before retrying. + + The privileged control path requires a running direct sandbox container that belongs to the named registry entry. Supported built-in images use either a direct root entrypoint or the OpenShell-managed process shape with OpenShell as PID 1 and exactly one nonroot `nemoclaw-start` supervisor. An arbitrary nonroot entrypoint that does not match the supported OpenShell-managed process shape fails with the `privileged control unavailable` failure layer. @@ -597,6 +770,8 @@ The managed nonroot supervisor continuously repairs those processes, stops an al That authorization keeps an authenticated host-requested exit out of the crash budget while its exact root controller remains live; it records host intent for the exit but does not claim that the host signal was the only possible cause in the shared-UID topology. The host repairs only the host-side OpenShell forwards after the supervisor reports a healthy gateway. + + For Hermes, both controllers validate `/sandbox/.hermes/.env` against the secret-boundary guard and validate the supervisor runtime environment before restart. The direct root-entrypoint supervisor verifies `/sandbox/.hermes/config.yaml` and `.env` against the root-owned strict hash and relaunches the process as the `gateway` user. The managed controller verifies the strict hash when both config inputs are root-owned and locked, but mutable managed config retains cold-start-equivalent trust and time-of-check/time-of-use limits. @@ -609,6 +784,8 @@ The shields transition keeps that lock through recursive filesystem updates, ver If a concurrent lifecycle request reports `SUPERVISOR_BUSY`, or a config or shields command reports `Hermes config mutation is already in progress`, wait for the active operation to finish and retry. Run `nemohermes shields down` before a Hermes config or inference change; these commands refuse to mutate a shields-up sandbox. + + The command can fail at these layers: unsupported agent, privileged control unavailable, secret-boundary refusal, unsafe config path, config hash mismatch when a strict hash is available, launch failure, health timeout, or forward recovery failure. An older direct-container image without the matching supervisor or managed controller helper reports `privileged control unavailable` and requires `nemohermes rebuild --yes`. Ordinary OpenShell exec and manual in-sandbox relaunch are not fallback paths. @@ -682,6 +859,36 @@ The command also tails `/tmp/gateway.log` inside the default sandbox and flags T nemohermes my-assistant status ``` + + +#### Checking the OpenClaw version + +NemoClaw pins the OpenClaw version inside the sandbox at build time, not at runtime. +The NemoClaw runtime build target is declared by `OPENCLAW_VERSION` in the NemoClaw Dockerfiles. +The `min_openclaw_version` field in `nemoclaw-blueprint/blueprint.yaml` remains the compatibility floor for direct blueprint consumers, so it can be lower than the Dockerfile target. +Existing sandboxes do not auto-upgrade when a newer NemoClaw release ships a newer pin. +Upgrade by rebuilding the sandbox. + +`nemohermes status` prints the running OpenClaw version on the `Agent` line: + +```bash +nemohermes my-assistant status +``` + +Expected output: + +```text +... + Agent: OpenClaw v2026.5.27 +... +``` + +If the sandbox is running an OpenClaw older than the version this NemoClaw release pins, `status` and `connect` add an `Update` line pointing at `nemohermes rebuild` to pick up the newer version. +The rebuild reuses the existing sandbox name and persisted credentials, so messaging tokens and provider keys carry over. + + + + #### Checking the Hermes version NemoClaw pins the Hermes version inside the sandbox image at build time, not at runtime. @@ -705,6 +912,8 @@ Expected output: If the sandbox is running an older Hermes version than this NemoClaw release expects, `status` and `connect` add an `Update` line pointing at `nemohermes rebuild` to pick up the newer version. The rebuild reuses the existing sandbox name and persisted credentials, so messaging tokens and provider keys carry over. + + ### `nemohermes doctor` Run a focused health check for one sandbox and the host services it depends on. @@ -714,6 +923,25 @@ Warnings do not make the command fail. Failed checks exit non-zero so scripts can use `doctor` as a readiness gate. Use `--json` for machine-readable output. + + +For OpenClaw sandboxes, `doctor` also checks the mutable config permission contract. +If `openclaw doctor --fix` was run inside the sandbox, it can tighten `/sandbox/.openclaw` and `openclaw.json` to a single-user `700/600` layout, which stops the gateway from persisting config changes. +`doctor` reports this as a `Config permissions` warning; pass `--fix` to restore the group-writable `2770/660` contract without rebuilding. +Restarting the sandbox repairs the same drift automatically. + +```bash +nemohermes my-assistant doctor [--json | --fix] +``` + +| Flag | Description | +|------|-------------| +| `--json` | Emit the report as JSON | +| `--fix` | Restore the mutable OpenClaw config permission contract if it was tightened. Mutually exclusive with `--json` | + + + + ```bash nemohermes my-assistant doctor [--json] ``` @@ -722,14 +950,27 @@ nemohermes my-assistant doctor [--json] |------|-------------| | `--json` | Emit the report as JSON | + + ### `nemohermes exec` Run a command non-interactively inside a running sandbox through the OpenShell exec endpoint. The command runs as the sandbox user with `HOME=/sandbox`. Use `--` to separate `exec` options from the command you want to run inside the sandbox. + + +After the remote command exits, NemoClaw verifies and, when needed, restores the mutable OpenClaw config permission contract. +When cleanup succeeds, `exec` preserves the remote command's exit code. +When cleanup fails closed, `exec` returns the cleanup failure and reports both statuses on `stderr`. + + + + The command exits with the remote command's exit code. + + ```bash nemohermes my-assistant exec [--workdir ] [--tty|--no-tty] [--timeout ] -- [args...] ``` @@ -756,6 +997,34 @@ nemohermes my-assistant logs [--follow] [--tail |-n ] [--since dashboard-url` + + +Print the browser dashboard URL for a running sandbox. +For OpenClaw sandboxes this includes the authenticated URL fragment. +For agent dashboards that manage their own session, such as Hermes Agent, this prints the plain dashboard URL. +Use this when you are on a remote machine, using an SSH or reverse tunnel, or need a complete URL for a browser session. + +```bash +nemohermes my-assistant dashboard-url +nemohermes my-assistant dashboard-url --quiet +``` + +The default output includes a label and a warning. +Pass `--quiet` or `-q` to print only the URL to stdout so scripts can capture it: + +```bash +URL=$(nemohermes my-assistant dashboard-url --quiet) +``` + + +Treat the authenticated dashboard URL like a password. +Do not log it, share it, or commit it to version control. +This warning applies when the command prints an OpenClaw tokenized URL. + + + + + Print the browser dashboard URL for a running Hermes sandbox. Hermes manages dashboard sessions itself, so this command prints a plain URL without an OpenClaw `#token=` fragment. The built-in dashboard is forwarded on port `18789` by default. @@ -768,13 +1037,50 @@ nemohermes my-assistant dashboard-url --quiet The Hermes OpenAI-compatible API remains separate on port `8642` and uses `/v1` for OpenAI-compatible clients. Use `nemohermes my-assistant status` to see both the dashboard and API endpoints. + + ### `nemohermes gateway-token` + + +Print the OpenClaw gateway auth token for a running sandbox to stdout. +The token is required by `openclaw tui` and the OpenClaw dashboard URL. +Use `dashboard-url` for browser access; use `gateway-token` only when automation needs the raw token. +Pipe it into automation or capture it into an environment variable: + +```bash +TOKEN=$(nemohermes my-assistant gateway-token --quiet) +export OPENCLAW_GATEWAY_TOKEN="$TOKEN" +``` + +The token is written to stdout with no surrounding text. +A one-line security warning is written to stderr; pass `--quiet` (or `-q`) to suppress it. +The command exits non-zero with a diagnostic on stderr when the sandbox is not registered or when the token cannot be retrieved (for example, if the sandbox is not running). + +The token also authenticates the Control UI config endpoint served by the gateway on the forwarded dashboard port. +There is no `controlui.bootstrap.config.json` path; the supported endpoint is `/__openclaw/control-ui-config.json`, and it requires the token (unauthenticated requests return `401` with a JSON body): + +```bash +TOKEN=$(nemohermes my-assistant gateway-token --quiet) +curl -fsS -H "Authorization: Bearer $TOKEN" \ + "http://127.0.0.1:18789/__openclaw/control-ui-config.json" +``` + + +Treat the gateway token like a password. +Do not log it, share it, or commit it to version control. + + + + + `gateway-token` is not applicable to Hermes sandboxes. Hermes API access uses bearer-token authentication configured through the Hermes runtime, not the OpenClaw gateway token. For browser access to the dashboard, use `nemohermes my-assistant dashboard-url`; Hermes dashboard auth is read from the in-sandbox config (`/sandbox/.hermes/config.yaml`), not a gateway token. If you need the endpoint for an OpenAI-compatible client, use `nemohermes my-assistant status` and the API URL it reports. + + ### `nemohermes destroy` Stop the NIM container, remove the host-side Docker image built during onboard, and delete the sandbox. @@ -1122,9 +1428,22 @@ nemohermes my-assistant skill install ./my-skill/ The skill directory must contain a `SKILL.md` file with YAML frontmatter that includes a `name` field. Skill names must contain only alphanumeric characters, dots, hyphens, and underscores. + + +OpenClaw plugins are a different kind of extension. +To install an OpenClaw plugin, refer to [Install OpenClaw Plugins](../manage-sandboxes/install-openclaw-plugins). +For OpenClaw, the command uploads the skill to the OpenClaw state directory and mirrors it into `$HOME/.openclaw/skills/` when the agent home directory differs from the state directory. +That mirror makes skills listed by `openclaw skills list` available at session startup. +If mirror creation fails, NemoClaw prints a warning so you can reinstall or inspect the home directory permissions. + + + + Hermes plugins are different from NemoClaw skills. `skill install` uploads agent skills, while Hermes plugin configuration is managed by the Hermes runtime and the NemoClaw Hermes plugin baked into the sandbox image. + + Run `nemohermes skill install --help` to print usage for this subcommand. If you pass a plugin-shaped directory to `skill install`, the CLI prints a plugin-specific hint instead of treating it as a missing skill file. @@ -1139,8 +1458,17 @@ For new installs, the agent session index is refreshed so the agent discovers th Remove an installed skill from a running sandbox by skill name. The command validates the skill name, removes the sandbox upload directory, and refreshes the agent session index so the remaining skills are rediscovered on the next session. + + +For OpenClaw, the command also removes the OpenClaw home-directory mirror when present. + + + + Run `nemohermes gateway restart` if prompted so the removal takes effect. + + ```bash nemohermes my-assistant skill remove my-skill ``` @@ -1181,6 +1509,26 @@ nemohermes my-assistant agents delete work nemohermes my-assistant agents delete work --force --json ``` + + +### `nemohermes agents apply` + +Reconcile the live sandbox roster against a declarative [agents.yaml manifest](../inference/declarative-agents-manifest). +The verb lists current agents via `openclaw agents list --json`, diffs them against the manifest, and adds missing secondaries or deletes orphan ones through `openclaw agents add|delete`. +Per-agent `model`, `subagents.*`, `tools`, top-level `defaults`, and `main` overrides need a sandbox rebuild and are surfaced as warnings rather than silently dropped; rerun `nemohermes onboard --agents --recreate-sandbox` to bake those fields. +When the diff removes orphan agents, NemoClaw invokes OpenClaw's confirmation-skipping delete mode internally. +`--non-interactive` controls the host-side `agents apply` prompt and is not forwarded to OpenClaw's delete command. + +```bash +nemohermes my-assistant agents apply -f ./agents.yaml +nemohermes my-assistant agents apply -f ./agents.yaml --yes +nemohermes my-assistant agents apply -f ./agents.yaml --yes --non-interactive +``` + +Pass `-f` / `--file ` to point at the manifest; `--yes` confirms the roster diff above; `--non-interactive` fails fast when `--yes` is absent so scripted callers cannot accidentally hang on a missing prompt. + + + ### `nemohermes sessions` List OpenClaw conversation sessions in the sandbox. @@ -1260,12 +1608,26 @@ Hermes stores session history in a SQLite database, so the command refuses posit `--agent` accepts only `hermes` as a no-op alias on a Hermes sandbox and rejects any other value. The host destination defaults to `./sessions-.jsonl`; `--out` picks a different path. + + +```bash +nemohermes my-assistant sessions export +nemohermes my-assistant sessions export main --agent main +nemohermes my-assistant sessions export agent:work:telegram:t-1 --include-trajectory +nemohermes my-assistant sessions export --format tar --out ./bundles/alpha.tgz --json +``` + + + + ```bash nemohermes my-assistant sessions export nemohermes my-assistant sessions export --agent hermes --out ./sessions-my-assistant.jsonl nemohermes my-assistant sessions export --json ``` + + | Flag | Description | |------|-------------| | `--agent ` | OpenClaw: agent id when `` are aliases rather than the canonical `agent::` form. Hermes: accepts only `hermes` as a no-op alias and rejects any other value. | @@ -1328,11 +1690,20 @@ If any required state path still cannot be backed up, `rebuild` exits before des When rebuild starts with shields up, NemoClaw opens a 30-minute shields-down window for backup and recreation. A detached auto-lock timer remains active until NemoClaw commits a successful shields-up state, so it can attempt to restore lockdown if the host rebuild process exits unexpectedly. + + +After restore, the command runs `openclaw doctor --fix` for cross-version structure repair. + + + + After restore, the command restores Hermes manifest-defined state and starts the rebuilt Hermes gateway with the regenerated `/sandbox/.hermes` config. For an older Hermes image that predates sealed shields transitions, rebuild is the only workflow authorized to use the descriptor-safe compatibility transition. The compatibility path verifies the strict root-owned hash and the in-tree hash, publishes fresh config inodes to revoke retained write descriptors, and restores the trusted lock posture if the transition cannot finish. Ordinary `shields up` and `shields down` commands refuse the older protocol and direct you to rebuild. + + ### `nemohermes update` Check for a NemoClaw CLI update and, when requested, run the maintained installer flow. @@ -1571,8 +1942,17 @@ nemohermes tunnel start Stop host auxiliary services that `nemohermes tunnel start` started (for example cloudflared). + + +NemoClaw also tries to stop the OpenClaw gateway inside the selected or default sandbox, which stops in-sandbox messaging channel polling for that sandbox. + + + + For Hermes sandboxes, use channel lifecycle commands when you only want to pause messaging without interrupting the Hermes gateway. + + Use `nemohermes channels stop ` when you only want to pause one bridge without stopping the gateway. ```bash @@ -1644,10 +2024,19 @@ nemohermes inference get --json Switch the active inference provider or model for a NemoClaw-managed OpenClaw or Hermes sandbox. The command updates the OpenShell gateway route, patches the selected running agent config so it matches the route, recomputes the config hash, and updates the NemoClaw registry. + + +For OpenClaw, the patch updates the OpenClaw config provider namespace and selected model. + + + + For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) and does not rebuild or restart the gateway. Keeping the placeholder preserves dashboard and API authentication after provider switches. Under the `nemohermes` alias, it uses the registered Hermes sandbox when exactly one exists; otherwise pass `--sandbox ` to target one explicitly. + + By default, the command syncs the default registered sandbox. The command refuses before changing the OpenShell route when the selected sandbox has shields up. Run `nemohermes shields down`, apply the inference change, then run `nemohermes shields up` again. @@ -1916,6 +2305,12 @@ By default the forward stays on `127.0.0.1` (loopback only). Set `NEMOCLAW_DASHBOARD_BIND=0.0.0.0` before `nemohermes onboard` (or `nemohermes connect`) to bind the forward on all interfaces, which is useful when the host is reached over SSH or a cloud workstation. Only `0.0.0.0` enables the remote bind; other values are ignored. + + +When the remote bind is opted in, the dashboard auth flow accepts non-loopback origins. + + + ```bash export NEMOCLAW_DASHBOARD_PORT=19000 nemohermes onboard @@ -1926,6 +2321,13 @@ Defaults are unchanged when no variable is set. If `NEMOCLAW_DASHBOARD_PORT` or the port from `CHAT_UI_URL` is already occupied by another sandbox, onboarding scans `18789` through `18799` and uses the next free dashboard port. Pass `--control-ui-port ` to require a specific port. + + +For OpenClaw, `NEMOCLAW_DASHBOARD_PORT` controls the OpenClaw dashboard forward. + + + + For Hermes, `NEMOCLAW_DASHBOARD_PORT` controls the built-in dashboard forward, which defaults to `18789`. The Hermes OpenAI-compatible API remains separate on port `8642` and uses `/v1` for API clients. Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` only when you want Hermes' optional in-browser TUI tab. @@ -1935,6 +2337,8 @@ Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` only when you want Hermes' optional in-bro | `NEMOCLAW_DASHBOARD_PORT` | 18789 | Hermes built-in dashboard forward port | | `NEMOCLAW_HERMES_DASHBOARD_TUI` | 0 | Optional Hermes in-browser TUI tab | + + ### Onboarding Configuration The following variables let you tune onboarding without editing the Dockerfile or passing repeated flags. @@ -1965,6 +2369,25 @@ Set them before running `nemohermes onboard`. | `NEMOCLAW_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; refer to [Runtime Controls](../manage-sandboxes/runtime-controls). | | `NEMOCLAW_MODEL_ROUTER_PYTHON` | absolute path | Pins the host Python interpreter used to create the Model Router virtual environment. Strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to another python. Relative command names such as `python3.12` are rejected. When unset, NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, retains every interpreter whose version is in `[3.10, 3.14)` and whose `ensurepip`, `pyexpat`, `ssl`, and `venv` stdlib modules import cleanly, and tries `python -m venv` on each in priority order until one succeeds. Set the pin when the auto-discovered interpreter is broken (for example, Homebrew `python@3.14` with a `pyexpat` dlopen mismatch on macOS). | + + +OpenClaw-specific build-time agent configuration: + +| Variable | Format | Effect | +|----------|--------|--------| +| `NEMOCLAW_AGENT_TIMEOUT` | positive integer (seconds) | Overrides `agents.defaults.timeoutSeconds` in the built OpenClaw config. Raise for slow inference. | +| `NEMOCLAW_AUTO_PAIR_SLOW_INTERVAL_SECS` | positive number of seconds | Sets the post-pairing poll cadence for the in-sandbox OpenClaw auto-pair watcher. Defaults to `5` so late allowlisted CLI and browser scope upgrades are approved before clients time out. Raise only on load-sensitive gateways. | +| `NEMOCLAW_AUTO_PAIR_FAST_REENTRY_POLLS` | positive integer | Sets how many fast polls run after the watcher observes a fresh allowlisted scope-upgrade request. Defaults to `5`; set lower only when you need to reduce gateway polling. | +| `NEMOCLAW_AUTO_PAIR_FAST_REENTRY_INTERVAL_SECS` | positive number of seconds | Sets the fast-reentry interval after a fresh allowlisted scope-upgrade request. Defaults to `1`. | +| `NEMOCLAW_CONTEXT_WINDOW` | positive integer (tokens) | Overrides the model's context-window value in the built OpenClaw config. | +| `NEMOCLAW_MAX_TOKENS` | positive integer (tokens) | Overrides the model's `maxTokens` in the built OpenClaw config. | +| `NEMOCLAW_REASONING` | `true` or `false` | Overrides the model's reasoning-mode flag in the built OpenClaw config. | +| `NEMOCLAW_AGENT_HEARTBEAT_EVERY` | duration with `s`, `m`, or `h` suffix (for example `30m`, `1h`, or `0m`) | Overrides `agents.defaults.heartbeat.every` in the built OpenClaw config. Set `0m` to disable periodic agent turns. | +| `NEMOCLAW_EXTRA_AGENTS_JSON` | JSON array of OpenClaw secondary-agent entries | Adds secondary agents to `agents.list`. Refer to [Extra OpenClaw agents](#extra-openclaw-agents) for the entry schema, path constraints, and validation rules. | + + + + Hermes-specific provider authentication: | Variable | Format | Effect | @@ -1976,6 +2399,10 @@ Hermes-specific provider authentication: | `NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS` | comma-separated list | Back-compatible alias for `NEMOCLAW_HERMES_TOOL_GATEWAYS`. | | `NEMOCLAW_EXTRA_PLACEHOLDER_KEYS` | whitespace- or comma-separated list of upper-snake env keys | Adds operator-supplied OpenShell provider rows so per-profile credentials such as `TELEGRAM_BOT_TOKEN_AGENT_A` flow through the same out-of-process placeholder injection that the canonical channel tokens use, instead of being baked into each Hermes profile `.env` as raw text. Refer to [Extra placeholder keys](#extra-placeholder-keys) for the entry shape and validation rules. | + + + + #### Extra placeholder keys Set `NEMOCLAW_EXTRA_PLACEHOLDER_KEYS` before running `nemohermes onboard` when one container hosts multiple Hermes profiles and each profile needs its own messaging-bridge credential. @@ -2001,6 +2428,66 @@ Offending tokens emit one warning each and are skipped. If a referenced env is unset at onboard time, the matching provider row is registered with a null token; the `upsertMessagingProviders` helper then skips the row, so no placeholder is attached to the OpenShell gateway and no Hermes profile can resolve it. Export the credential before running `nemohermes onboard` for that profile. + + + + +#### Extra OpenClaw agents + +Set `NEMOCLAW_EXTRA_AGENTS_JSON` to either a JSON array of secondary-agent entries, or an object payload of the form `{"agents": [...], "defaults": {...}, "main": {...}}`, to bake them into `agents.list[]` at image build time. +Each entry must declare `id` and `tools`; `workspace`, `agentDir`, `subagents`, `description`, and `model` are optional. +The generator always writes the canonical `main` entry first with `default: true`, so secondary agents cannot displace the primary agent. +Malformed JSON or invalid entries fail the image build with a structured error. + +Field rules: + +- `id` must match `^[a-z][a-z0-9_-]{0,31}$` and must not be `main`. +- `workspace` defaults to `/sandbox/.openclaw/workspace-`; when set, it must be an absolute path that resolves to that value. +- `agentDir` defaults to `/sandbox/.openclaw/agents/`; when set, it must be an absolute path that resolves to that value. +- `tools` must declare a non-empty `allow[]` or `deny[]`; nothing is implicitly granted. +- `model`, when set, must be a `"provider/model"` string whose provider portion matches the primary onboard provider. +- `default: true` is rejected because the primary agent is the only default. +- Allowed entry fields: `id`, `workspace`, `agentDir`, `tools`, `subagents`, `description`, `model`. Any other key fails the image build (no implicit credential or env pass-through). +- Allowed `tools` fields: `profile`, `allow`, `deny`. Allowed per-agent `subagents` fields: `delegationMode`, `allowAgents`, `model`, `thinking`, `requireAgentId`. Any other nested key fails the image build. + +OpenClaw accepts `subagents.maxSpawnDepth` only on `agents.defaults.subagents`, never inside a per-agent `subagents` object. +The value must be an integer between `1` and `5` (OpenClaw's accepted range); to set it, use the object payload shape and pass it under `defaults`: + +```json +{ + "agents": [ + { + "id": "research", + "tools": { + "profile": "minimal", + "allow": ["web_search", "web_fetch", "read", "write"], + "deny": ["exec", "gateway"] + } + } + ], + "defaults": { + "subagents": { "maxSpawnDepth": 1 } + } +} +``` + +Array-shape example (paths defaulted): + +```json +[ + { + "id": "research", + "tools": { + "profile": "minimal", + "allow": ["web_search", "web_fetch", "read", "write"], + "deny": ["exec", "gateway"] + } + } +] +``` + + + #### Linux Ollama install mode details Set `NEMOCLAW_OLLAMA_INSTALL_MODE=system` to run the official `https://ollama.com/install.sh` installer, which uses sudo, writes to `/usr/local`, and configures systemd. @@ -2126,6 +2613,22 @@ The following flags change defaults for commands that manage existing sandboxes. | `NEMOCLAW_SHIELDS_SETTLE_MS` | milliseconds (default `750`, clamped to `0` to `10000`) | Settle window NemoClaw waits after re-applying a config lockdown (during shields auto-restore and `nemohermes shields up` drift remediation) before re-confirming the lock still holds. Detects when an in-sandbox reconciler changes config file permissions after lockdown and re-applies the lock; if NemoClaw cannot re-confirm the lock within the retry budget, shields stay down. This narrows the window in which a reconciler can revert permissions rather than eliminating it. The best-effort `chattr +i` immutable bit remains the only fully durable lock. Raise it on hosts where the gateway settles slowly. | | `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA` | `1` to opt in | Acknowledges data loss during `nemohermes uninstall` and removes the otherwise-preserved entries (`rebuild-backups/`, `backups/`, `sandboxes.json`) under `~/.nemoclaw/`. Equivalent to passing the `--destroy-user-data` flag; the global `Proceed?` confirmation still applies unless `--yes` is also passed. | + +### Remote Deployment + +The following variables seed defaults for `nemohermes deploy` and `nemohermes onboard --remote`, which provision a sandbox on a Brev instance. +Each has a flag equivalent on `deploy`; the env var lets non-interactive runs skip the prompt. +For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, refer to [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu). + +| Variable | Default | Effect | +|----------|---------|--------| +| `NEMOCLAW_BREV_PROVIDER` | `gcp` | Cloud provider for Brev instance creation. | +| `NEMOCLAW_GPU` | `a2-highgpu-1g:nvidia-tesla-a100:1` | GPU specification (instance type and GPU model) for the Brev instance. | +| `NEMOCLAW_DEPLOY_NO_CONNECT` | unset | When set to `1`, skips the automatic `connect` step after the remote deploy completes. | +| `NEMOCLAW_DEPLOY_NO_START_SERVICES` | unset | When set to `1`, skips starting services automatically after the remote deploy. | + + + ### Legacy `nemohermes setup` Deprecated. Use `nemohermes onboard` instead. diff --git a/docs/reference/host-files-and-state.mdx b/docs/reference/host-files-and-state.mdx new file mode 100644 index 00000000000..7b0e4906f01 --- /dev/null +++ b/docs/reference/host-files-and-state.mdx @@ -0,0 +1,72 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Host Files and State" +sidebar-title: "Host Files and State" +description: "Reference for host-side files and directories under ~/.nemoclaw, including the sandbox registry, backups, onboarding state, local inference adapter state, and uninstall preservation rules." +description-agent: "Lists the host-side ~/.nemoclaw files and directories, what creates them, whether uninstall preserves them, and when they are safe to remove. Use when auditing NemoClaw state, troubleshooting stale local state, or deciding what user data survives uninstall." +keywords: ["nemoclaw host files", "nemoclaw state files", "nemoclaw sandboxes.json", "nemoclaw backups", "nemoclaw uninstall user data"] +content: + type: "reference" +--- +NemoClaw stores host-side state under `~/.nemoclaw/`. +This page is the reference for what those files mean, when NemoClaw creates them, and whether they are user data or runtime state. + +The path is host-side unless a row explicitly says otherwise. +Do not confuse host `~/.nemoclaw/` with the sandbox's `/sandbox/.nemoclaw/` directory. + +## Naming Notes + +- The current sandbox registry file is `~/.nemoclaw/sandboxes.json`. +- There is no current `~/.nemoclaw/registry.json` file. Some code and tests call the registry concept "registry", but the persisted filename is `sandboxes.json`. +- The provider selection file is `/sandbox/.nemoclaw/config.json` inside the sandbox. Sandbox code may describe the same file as `~/.nemoclaw/config.json` because `HOME=/sandbox` there, but it is not a host-side `~/.nemoclaw/config.json` file. + +## User Data Preserved By Uninstall + +`$$nemoclaw uninstall` and `nemohermes uninstall` preserve these entries by default. +They are removed only when you pass `--destroy-user-data`, set `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1`, or answer the interactive data-loss prompt with `y`. + +| Path | Created by | Purpose | Safe to delete? | +|------|------------|---------|-----------------| +| `~/.nemoclaw/sandboxes.json` | `onboard`, sandbox lifecycle commands | Canonical host registry for sandbox names, default sandbox selection, gateway binding, dashboard ports, policy metadata, and agent-specific metadata. | Only when you intentionally want NemoClaw to forget local sandboxes. Prefer lifecycle commands over hand edits. | +| `~/.nemoclaw/rebuild-backups//` | `snapshot create`, `rebuild`, `backup-all` | Host-side sandbox state snapshots used for rebuild recovery and restore flows. | Yes, after you no longer need to recover or restore that sandbox state. | +| `~/.nemoclaw/backups//` | `scripts/backup-workspace.sh` and workspace backup flows | Manual workspace backups outside the live sandbox registry. | Yes, after you have another backup or accept losing that saved workspace copy. | + +## Runtime And Operational State + +Uninstall removes these entries unless they are part of a broader preserved directory you keep manually. +Most are regenerated automatically, but several should not be removed while an onboarding, rebuild, local adapter, or share mount is active. + +| Path | Created by | Purpose | Safe to delete? | +|------|------------|---------|-----------------| +| `~/.nemoclaw/onboard-session.json` | `onboard`, `onboard --resume`, rebuild flows | Resumable onboarding state, last completed step, selected provider/model, router PID, policy presets, and migration status. | Only to abandon a failed/resumable onboarding session after confirming no onboard or rebuild process is running. | +| `~/.nemoclaw/onboard.lock` | `onboard` and rebuild flows | File lock that prevents overlapping onboarding or rebuild mutations. | Usually no. Remove only when you have confirmed the owner process is gone and the lock is stale. | +| `~/.nemoclaw/ollama-proxy-token` | Local Ollama inference setup | Bearer token used by the host Ollama auth proxy; written with owner-only permissions. | Yes, to force token regeneration, but stop/restart the local Ollama proxy flow first. | +| `~/.nemoclaw/ollama-auth-proxy.pid` | Local Ollama inference setup | PID of the local Ollama auth proxy process so uninstall and recovery can stop matching processes. | Yes, if the referenced process is gone. A stale PID can be removed during proxy recovery or uninstall. | +| `~/.nemoclaw/bedrock-runtime-adapter-token` | Bedrock Runtime compatible adapter | Bearer token for the local Bedrock Runtime adapter. | Yes, to force adapter token regeneration after stopping the adapter. | +| `~/.nemoclaw/bedrock-runtime-adapter.pid` | Bedrock Runtime compatible adapter | PID of the local Bedrock Runtime adapter process. | Yes, if the referenced process is gone. | +| `~/.nemoclaw/bedrock-runtime-adapter.json` | Bedrock Runtime compatible adapter | Adapter state and compatibility metadata. | Yes, when resetting the adapter state after stopping it. | +| `~/.nemoclaw/bedrock-runtime-adapter.log` | Bedrock Runtime compatible adapter | JSONL diagnostic log for adapter events. | Yes, when logs are no longer needed for troubleshooting. | +| `~/.nemoclaw/credentials.json` | Earlier NemoClaw releases | Legacy plaintext credential store. Current flows migrate supported values into the OpenShell gateway and then remove this file after verified migration. | Delete only after confirming credentials were migrated or are no longer needed. If it remains unexpectedly, run onboarding to complete migration. | +| `~/.nemoclaw/source/` | Installer-managed installs and `update` | Managed source clone used by installer-based updates. | Yes, after uninstall or before a clean reinstall. Removing it can break `update` until NemoClaw is reinstalled. | +| `~/.nemoclaw/model-router-venv/` | Model Router setup | Python virtual environment for the local model router service. | Yes, after stopping the router. It is recreated when the router is prepared again. | +| `~/.nemoclaw/state/` | Shields, model-router, and local runtime helpers | Internal runtime records such as shields state and local service coordination. | Avoid manual deletion unless a support or recovery flow calls for it. | +| `~/.nemoclaw/mounts//` | `share mount` | Default host mount point for SSHFS sandbox file sharing. | Unmount first with `share unmount`; then the empty directory can be removed. | +| `~/.nemoclaw/usage-notice.json` | First-run usage notice flow | Records the accepted third-party software notice version. | Yes. Deleting it makes NemoClaw ask for consent again. | +| `~/.nemoclaw/managed_swap` | Linux preflight swap helper | Tracks a NemoClaw-managed swap file path for cleanup. | Do not delete by itself. Use the documented host cleanup path so the swap file and state stay in sync. | + +## Related Sandbox-Side State + +These entries are under the sandbox root, not the host state directory. + +| Path | Created by | Purpose | Safe to delete? | +|------|------------|---------|-----------------| +| `/sandbox/.nemoclaw/config.json` | Onboarding and rebuild config sync | Provider and model selection consumed by the in-sandbox NemoClaw/OpenClaw integration. | No during normal use. Re-run onboarding or rebuild to regenerate it. | +| `/sandbox/.nemoclaw/state/` | In-sandbox runtime guards | Sandbox-side mutable state allowed by the filesystem policy. | No during normal use. Use sandbox lifecycle commands instead. | + +## Related References + +- [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle) covers uninstall and `--destroy-user-data`. +- [Backup and Restore](../manage-sandboxes/backup-restore) covers `rebuild-backups/` and workspace backups. +- [Credential Storage](../security/credential-storage) covers legacy `credentials.json` migration. +- [Local Inference](../inference/use-local-inference) covers the Local Ollama proxy token. diff --git a/test/host-files-state-doc.test.ts b/test/host-files-state-doc.test.ts new file mode 100644 index 00000000000..d9ce3d9f530 --- /dev/null +++ b/test/host-files-state-doc.test.ts @@ -0,0 +1,49 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +/** + * Documentation gate for the unified host-side state reference (#6088). + */ + +import { readFileSync } from "node:fs"; +import path from "node:path"; +import { describe, expect, it } from "vitest"; + +const repoRoot = path.resolve(import.meta.dirname, ".."); + +const doc = readFileSync(path.join(repoRoot, "docs/reference/host-files-and-state.mdx"), "utf8"); +const nav = readFileSync(path.join(repoRoot, "docs/index.yml"), "utf8"); + +describe("Host files and state documentation (#6088)", () => { + it("is listed in both OpenClaw and Hermes reference navigation", () => { + const matches = nav.match(/path: reference\/host-files-and-state\.mdx/g) ?? []; + expect(matches).toHaveLength(2); + }); + + it("covers the host-side files and directories called out by the issue", () => { + for (const entry of [ + "~/.nemoclaw/sandboxes.json", + "~/.nemoclaw/rebuild-backups//", + "~/.nemoclaw/backups//", + "~/.nemoclaw/onboard-session.json", + "~/.nemoclaw/onboard.lock", + "~/.nemoclaw/ollama-proxy-token", + "~/.nemoclaw/credentials.json", + "~/.nemoclaw/mounts//", + ]) { + expect(doc).toContain(entry); + } + }); + + it("clarifies registry.json is not the current persisted registry filename", () => { + expect(doc).toContain("There is no current `~/.nemoclaw/registry.json` file"); + expect(doc).toContain("the persisted filename is `sandboxes.json`"); + }); + + it("separates host state from sandbox-side config.json", () => { + expect(doc).toContain("Do not confuse host `~/.nemoclaw/`"); + expect(doc).toContain("/sandbox/.nemoclaw/config.json"); + expect(doc).toContain("because `HOME=/sandbox` there"); + expect(doc).toContain("it is not a host-side `~/.nemoclaw/config.json` file"); + }); +});