Manage SandboxesConfigure Sandboxes

Understand Runtime Changes

View as Markdown

Use this matrix to choose the operation that makes a sandbox change take effect. Some changes apply at runtime, while image and filesystem changes require a rebuild or re-onboard.

OpenClaw Runtime Changes

ItemWhen the change takes effectHow to change it
Inference providerRuntime route and config update; rebuild only if you need to recreate the imageRun nemoclaw inference set
Inference model on the current providerRuntime route and config updateRun nemoclaw inference set
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 apply at runtime, 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.

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 and temporarily seals fresh inodes while the root PID 1 supervisor replaces the gateway child. 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 hash drift, restart refuses while the old healthy gateway is still serving.

Mutable Agent State

NemoClaw does not provide post-provisioning immutability for agent configuration or persistent state. OpenShell remains authoritative for sandbox filesystem and network policy enforcement. An agent process can change files that its sandbox identity can write.

Use supported host commands for intended configuration changes so NemoClaw updates validation hashes and managed metadata with the config. Direct in-sandbox edits can cause a later gateway restart to reject the changed config when its integrity metadata no longer matches.

NemoClaw serializes host-side gateway recovery, config and inference writes, snapshots, policy updates, channel updates, and sandbox destruction for each sandbox. This mutation lock prevents concurrent host operations from racing on the same registered sandbox.