Manage SandboxesConfigure Sandboxes

Understand Runtime Changes

View as Markdown

Use this matrix to choose the operation that makes a sandbox change take effect. NemoClaw applies its security posture in three layers: what onboarding writes into the sandbox image, what the running sandbox can hot-reload, and what requires a rebuild or re-onboard.

OpenClaw Runtime Changes

ItemWhen the change takes effectHow to change it
Inference providerRuntime route and config update while shields are down; rebuild only if you need to recreate the imageRun nemoclaw <name> shields down, then nemoclaw inference set, then restore shields
Inference model on the current providerRuntime route and config update while shields are downRun nemoclaw <name> shields down, then nemoclaw inference set, then restore shields
Sub-agentRe-onboard required because the sub-agent and workspace are baked at onboardnemoclaw onboard --recreate-sandbox
Network policy presetRuntime on the next request; rebuild only if the preset adds bind-mounted secretsnemoclaw <name> policy add <preset> or policy remove <preset>
Network allowlistRuntime on the next requestopenshell policy set or the interactive approval prompt at the gateway
Channel tokensRebuild required because the channel configuration and credential attachment are created during onboarding or rebuildnemoclaw <name> channels add <channel>, then accept the rebuild prompt
Channel enable or disableRebuild required because openclaw.json is the runtime source of truthnemoclaw <name> channels stop <channel>, then rebuild
Dashboard forward portRuntime; the port is re-resolved on the next connectNEMOCLAW_DASHBOARD_PORT=<port> nemoclaw <name> connect
Dashboard bind addressBuild and runtime; an existing local-only sandbox must be recreated with the remote-bind opt-inNEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemoclaw onboard --recreate-sandbox, then use the same variable with connect
Gateway process environment or startup-only plugin stateRuntime after gateway restartnemoclaw <name> gateway restart
Default workspace template seedLocked at first sandbox boot; re-onboard required to change the bake-time choiceSet NEMOCLAW_MINIMAL_BOOTSTRAP=1 before nemoclaw onboard to skip default template seeding for new or pristine workspaces; existing files are not deleted
Web search providerRebuild required because onboarding bakes the provider plugin configuration and credential attachment into the imageSet NEMOCLAW_WEB_SEARCH_PROVIDER=brave, tavily, or none, then rerun onboarding and recreate the sandbox
Filesystem layoutLocked at creationRe-onboard with nemoclaw onboard --recreate-sandbox
Sandbox nameLocked at creationRe-onboard with a different --name
GPU passthrough or device selectorLocked at creationRe-onboard with --gpu or --sandbox-gpu-device
agents.listRuntime; OpenClaw hot-reloads on config changePrefer agent or NemoClaw commands that keep host and sandbox state aligned
openclaw.json keysMixed; supported config and inference updates run while shields are down, while image, policy, web search, and channel changes can require rebuildUse nemoclaw inference set or nemoclaw <name> config set so the config and integrity hash change together

For a new or pristine OpenClaw workspace, NEMOCLAW_MINIMAL_BOOTSTRAP=1 avoids roughly 3,000 tokens of per-turn project-context overhead by skipping the default template seed. It does not delete existing workspace files.

The runtime source of truth is /sandbox/.openclaw/openclaw.json. The host registry caches metadata, but the image and OpenClaw read from the in-sandbox file.

OpenClaw config and inference changes are refused while shields are up. Run nemoclaw <name> shields down before the change, then restore lockdown with nemoclaw <name> shields up.

Host-side OpenClaw config writes run under the per-sandbox transition lock and bind the replacement to the SHA-256 digest of the matching read. Before config set replaces the live file, NemoClaw validates the complete candidate with the installed OpenClaw runtime. If candidate validation fails, the command preserves the existing config and does not reach the gateway restart path. The root-only config guard validates bounded JSON input, transactionally publishes fresh config and hash inodes, and restores the prior mutable posture without adopting concurrent path changes.

In the direct root-entrypoint topology, gateway restart performs a read-only config and hash preflight, temporarily seals fresh inodes while the root PID 1 supervisor replaces the gateway child, and then restores the prior shields posture. In the OpenShell-managed topology, the installed root controller performs the config preflight while the nonroot nemoclaw-start supervisor replaces the gateway child.

Mutable config in the managed topology keeps the same trust and time-of-check/time-of-use limits as a managed cold start and does not receive the direct root-entrypoint restart seal. If preflight detects an unsafe path, invalid config, invalid ownership posture, or locked hash drift, restart refuses while the old healthy gateway is still serving.

Timed Shields Windows

NemoClaw serializes host-side gateway recovery, config and inference writes, snapshot mutation, sandbox destruction, and shields transitions for each sandbox. When shields down --timeout is active, each mutation binds to that exact timer generation so a replaced or expired timer cannot race a later command or a new sandbox that reuses the same name.

Restore Lockdown After Expiration

If the timeout expires while a mutation is changing sandbox state, auto-restore closes the per-sandbox lifecycle deadline gate. The gate blocks new mutations and waits for the recorded live owner to release its exact lock generation. NemoClaw does not signal that process because portable process inspection cannot prove that all descendants stopped. After the owner releases the lock, auto-restore restores the restrictive policy and configuration posture. The ownership check includes both the process ID and process start identity so PID reuse does not grant control over an unrelated process.

Complete Exact-Generation Recovery

An interactive command can take over an expired timer. Interactive recovery has separate transition-takeover and restoration phases. Each phase makes up to 7 attempts and waits 5 seconds between failures, for up to 30 seconds of retry delay per phase. Detached recovery uses one 7-attempt budget across deadline setup, main-generation publication, and restoration. The deadline gate remains closed during those attempts.

If restoration cannot commit, NemoClaw attempts to record durable containment. If that containment commit also fails, NemoClaw retains any exact lifecycle and deadline gates it already owns. A state-directory failure that prevented gate publication also prevents normal mutation-lock acquisition. Correct the reported state-directory write failure, then run nemoclaw <name> shields status to resume recovery or receive exact-generation recovery guidance. When recovery cannot complete, an interactive command returns an error, or the detached timer exits with a failure status.

NemoClaw also records durable containment when an owner exits before it can prove that the owner’s descendants stopped, or when ownership becomes ambiguous. Durable containment, retained exact gates, or the fail-closed state-directory error keeps new mutations blocked until you complete exact-generation operator recovery.

Stop all NemoClaw processes for the sandbox, then follow the paths, identities, tokens, and removal order in the reported error. Verify each recorded generation is unchanged, remove only the exact stale generations first, and remove the exact containment generation last.

Preserve Managed MCP Policy

Before a manual Shields transition replaces a policy, NemoClaw requires exact Model Context Protocol (MCP) agreement among the sandbox registry, generated-policy record, and live gateway policy. shields down carries the proven managed MCP policy entries into the relaxed policy. Restoration removes snapshot-time managed MCP entries before it overlays current exact entries. If exact agreement is absent, a manual Shields transition refuses the replacement policy.

At an expired deadline, auto-restore omits unproven managed MCP policy entries, restores lockdown, and records the omission count in its audit entry. An MCP server removed during the shields-down window stays removed. A surviving server keeps its recorded endpoint and address pins while its policy ownership remains exact.