Run Sandboxes
Use these workflows to keep existing sandboxes reachable and control the resources they consume.
Manage Dashboard Ports
If a managed forward stopped or the URL does not load, restore its identity-bound lifecycle through NemoClaw.
For lower-level diagnostics, list OpenShell’s legacy and user-managed forwards separately. Receipt-owned ForwardTcp services are verified by nemoclaw <name> status and recover.
Run Multiple Sandboxes
Choose a distinct sandbox name of 1 to 19 characters before onboarding.
The limit matches OpenShell’s routed sandbox-name limit and applies to every agent runtime.
For the complete naming rules, refer to onboard --name.
Each sandbox needs its own dashboard port because openshell forward refuses to bind a port that another sandbox already uses.
When the default port is already held by another sandbox, nemoclaw onboard scans ports 18789 through 18799 and uses the next verified available port.
When allocating ports for a new sandbox, NemoClaw skips candidates whose OpenShell forward ownership cannot be verified. It can select a later candidate only when that port is verified available. If no candidate is available, the error lists each blocked port, including a preferred dashboard port outside the default range. When every candidate has unverified ownership, inspect ownership before rerunning onboarding. For mixed failures, the error includes both verification recovery and the existing occupied-port remedies. Refer to Port already in use for those recovery actions.
If you intentionally run separate OpenShell gateways on the same host, set a different NEMOCLAW_GATEWAY_PORT before each onboarding run.
NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another.
Sandbox-scoped commands, including exec, status, start, and stop, address the sandbox through its recorded gateway binding. NEMOCLAW_GATEWAY_PORT selects the gateway for onboarding and new gateway-scoped setup; it does not redirect an existing sandbox command.
A non-default NEMOCLAW_GATEWAY_PORT also gets its own host state root at ~/.nemoclaw/gateways/<port>/, with a separate sandbox registry, rebuild backups, and legacy credential-migration files, so gateway-scoped state stays segregated while shared host-level files remain under ~/.nemoclaw/.
On first use after upgrading, NemoClaw moves legacy rows and related state only when their recorded gateway identity matches the selected port; ambiguous state is left untouched with remediation.
Provider credentials remain in the OpenShell gateway store.
The default port keeps the shared ~/.nemoclaw/ location.
When other ports remain, nemoclaw uninstall removes only the selected gateway and keeps the shared CLI, services, images, providers, configuration, models, and swap.
Gateway and dashboard cleanup is scoped by sandbox name and port.
A later onboarding run that uses a different NEMOCLAW_GATEWAY_PORT or --control-ui-port does not tear down the first sandbox’s gateway or dashboard forward.
Repeated onboarding and resume keep the sandbox’s registered dashboard port and restore a missing forward on that port. If the port is already bound, NemoClaw verifies that the listener is the exact OpenShell forward for that sandbox and reuses it without restarting the sandbox. For that registered port, another sandbox’s registration, a foreign listener, or unverified ownership still stops onboarding with a port conflict error.
To choose a specific port, pass --control-ui-port:
You can also set CHAT_UI_URL or NEMOCLAW_DASHBOARD_PORT before onboarding:
For port conflicts and overrides, refer to Port already in use.
Stop and Start a Sandbox
Stop a sandbox through OpenShell to free CPU, memory, and GPU resources without losing anything:
Workspace files, credentials, network policies, and the registry entry are preserved. OpenShell stops the sandbox’s provider workload. After the sandbox stops, NemoClaw attempts to stop that sandbox’s host dashboard forward. The shared host gateway and tunnel services keep serving other sandboxes.
Start it again later:
After OpenShell accepts the start, NemoClaw waits for it to report the sandbox in the Ready or Running state.
NemoClaw recovers missing agent processes and host forwards only after that phase, so a slow sandbox start does not need a separate recover command.
Refer to nemoclaw <name> stop and nemoclaw <name> start for details.
Use nemoclaw <name> destroy when you want to delete the sandbox instead.
Manage the Cloudflare Tunnel
When the host has cloudflared, nemoclaw tunnel start starts a Cloudflare tunnel.
The tunnel can expose the dashboard with a public URL.
NemoClaw manages one tunnel for the selected OpenShell gateway port, independent of individual sandbox lifecycles.
Stopping, destroying, or recreating a sandbox does not stop that tunnel.
Set CLOUDFLARE_TUNNEL_TOKEN before running the command when you want to use a Cloudflare named tunnel instead of a generated quick-tunnel URL.
If command-line inspection is unavailable, Windows can still verify and stop a recorded cloudflared.exe through an identity-bound process handle. Other platforms require process inspection before signaling. If NemoClaw cannot verify the process identity or stop it safely, it refuses to create a second tunnel; restore inspection access or independently verify and stop the process before retrying. nemoclaw tunnel status reports this recovery state.
nemoclaw tunnel stop stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox.
An explicitly set NEMOCLAW_GATEWAY_PORT selects the host tunnel state.
Otherwise, tunnel commands use the selected or default sandbox’s owning gateway, falling back to the process-default gateway when no sandbox resolves.
If the sandbox name belongs to more than one gateway registry, tunnel-state selection fails closed.
After an upgrade, when no live gateway-scoped PID record exists and exactly one live legacy PID record matches a sandbox in the selected gateway registry, NemoClaw moves that record into gateway-scoped state.
If NemoClaw cannot inspect that PID’s process identity, it preserves the record and refuses to start a second tunnel.
If multiple live PID records exist, the command reports the conflict and requires you to stop the unintended process through its process manager before starting a tunnel.
On non-Windows hosts, NemoClaw scans the current user’s process list when no live managed tunnel record exists.
It reports an unrecorded cloudflared executable as a conflict.
Windows skips this scan.
If process listing fails on another platform, tunnel start fails closed without starting a tunnel, and status cannot report unmanaged conflicts until process inspection is restored.
If NemoClaw reports incomplete tunnel cleanup, independently verify and stop the recorded cloudflared process with the host process manager, keep the PID record until that process exits, then retry the command.
The older nemoclaw start now prints migration guidance and exits successfully without starting
a sandbox or tunnel. Use nemoclaw <name> start or nemoclaw tunnel start explicitly.
Related Topics
- View Sandbox Status before changing a sandbox.
- Recover and Rebuild Sandboxes when start does not restore a healthy runtime.
- Troubleshooting for port, gateway, and dashboard failures.