Skip to navigation
Manage SandboxesConfigure Sandboxes

Understand Gateway Lifecycle Control

View as Markdown

Built-in OpenClaw and Hermes images leave agent gateway lifecycle with the native agent runtime. OpenShell owns sandbox containment and the authoritative sandbox lifecycle phase. NemoClaw resolves the registered sandbox, invokes the native command through that OpenShell sandbox, and observes the result.

ComponentResponsibility
OpenShellSelects and contains the sandbox, projects approved credentials, and records the authoritative sandbox lifecycle phase.
Native agent runtimeOwns the agent gateway, background work, cron work, hooks, and child processes.
NemoClaw host CLIResolves the registered sandbox and agent, invokes the native lifecycle command, verifies gateway health, and repairs host-side forwards.

NemoClaw does not signal a gateway process, authorize a process exit, or respawn an agent-owned process. It does not add a second gateway lifecycle controller inside the sandbox.

Verify Recovery Health

gateway restart invokes the native OpenClaw or Hermes lifecycle command through the selected OpenShell sandbox. For OpenClaw, NemoClaw polls /readyz for HTTP 200 and JSON {"ready":true} before it repairs host-side forwards or reports success. For Hermes, NemoClaw polls the agent health endpoint for the timeout declared in the agent manifest. It waits through the shared settle window and requires the gateway to remain healthy before it reports success.

recover checks the native health endpoint. If a built-in gateway is stopped, recover reports that state instead of relaunching the process. Use gateway restart to request a native restart, or restart the sandbox through OpenShell when the native command cannot run.

Fail Closed on Unsupported Runtimes

NemoClaw runs the lifecycle command only after it resolves a supported gateway runtime for the registered sandbox. Terminal agents fail as unsupported because they do not have an agent gateway. An absent agent definition or a native command failure stops the operation before host-forward repair.

For gateway lifecycle, NemoClaw does not fall back to direct provider-container mutation or manual process signaling. If the sandbox cannot run the current native lifecycle command, update its image:

nemoclaw <name> rebuild --yes