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. 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 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.

If the timeout expires while a mutation is still changing sandbox state, auto-restore can stop that exact process tree, reclaim the transition, and restore the restrictive policy and config posture. The ownership check includes both the process ID and process start identity so PID reuse does not grant control over an unrelated process.

Retry a command that the auto-restore deadline interrupts after you open a new shields-down window.