System Readiness

Use the system readiness report to inspect host prerequisites and OpenShell gateway authority before you run onboarding. The command works without a registered gateway or sandbox.

Run the readiness check

Run the human-readable check from the host:

$
nemo-deepagents host probe

Use JSON when another tool consumes the result:

$
nemo-deepagents host probe --json

Both presentations use the same structured report. The JSON report includes its schemaVersion, status, exitCode, observations, capabilities, qualifications, findings, evidence, and provenance. It also includes mutated: false.

Interpret exit codes

The command uses deterministic exit codes:

The command writes a schema-valid JSON report for all three results. Read the report before you handle a nonzero exit.

Use the compatibility contract

The schemaVersion field uses major.minor.patch format. Consumers must reject an unknown major version. Consumers can ignore fields that they do not recognize within major version 1. Use stable capability and finding IDs instead of parsing human summaries. Treat bounded evidence as diagnostic context unless an observation, capability, or finding references that evidence ID.

Verify the Report Producer

Schema version 1.1.0 adds a required immutable identity for the CLI build that produced the report. The identity is present for supported, incompatible, and inconclusive reports.

A Git-described version can use a value such as 0.0.96-35-g8bfff4526. The version must begin with three dot-separated digit groups. It can add an alphanumeric prerelease suffix after - and an alphanumeric build suffix after +; each suffix can also contain . and - separators. The revision after g must match the leading characters of sourceRevision. Packaged releases retain the full revision in their compiled build identity when Git metadata is unavailable at runtime.

A strict scenario must fail closed before it uses readiness facts. Apply these checks in order:

1. Reject an unknown schema major version.
2. Require schemaVersion 1.1.0 or later within schema major 1.
3. Compare the leading X.Y.Z release identity in nemoclawVersion with the scenario minimum.
4. If the scenario supplies an expected source revision, require an exact sourceRevision match.
5. If nemoclawVersion has a Git revision suffix, require it to match sourceRevision.
6. Require status: "supported" and retain the producer identity in the admission receipt.

An admission receipt can retain this bounded projection:

1
{
2
  "readinessStatus": "supported",
3
  "readinessProducer": {
4
    "schemaVersion": "1.1.0",
5
    "nemoclawVersion": "0.0.96-35-g8bfff4526",
6
    "sourceRevision": "8bfff4526aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
7
  }
8
}

Retain the full sourceRevision even when the scenario accepts every build above a minimum release. Do not use observedAt as build identity.

Interpret Docker storage

The report rejects an unsupported explicit DOCKER_HOST before it uses Docker daemon evidence. host.docker.host_invalid records whether the configured endpoint is invalid, host.docker.endpoint_supported is absent when a configured endpoint is not an absolute local unix:// socket, and the blocking host.docker.host_invalid finding identifies that condition. TCP, SSH, relative Unix socket, and unsafe path values do not fall back to the default Docker socket. When DOCKER_HOST is unset, NemoClaw first probes the Docker CLI’s selected authority, including DOCKER_CONTEXT and its DOCKER_CONFIG directory when set, without a host override. If that authority is unreachable, NemoClaw probes a bounded set of local Unix sockets and accepts only an endpoint with valid server-version evidence. When it selects a fallback socket, NemoClaw clears the unreachable DOCKER_CONTEXT so later Docker commands use the selected DOCKER_HOST. A mixed set of reachable Docker and Podman fallbacks, or a fallback with an unknown server identity, produces no automatic DOCKER_HOST override. A reachable Podman endpoint remains classified as Podman and does not satisfy the standard Docker runtime requirement.

The Docker storage capabilities separate the current host configuration from NemoClaw’s supported remediation path.

Use host.docker.storage_compatible when a consumer requires compatibility before mutation. The strict internal readiness report remains incompatible with exit code 2 until a consumer applies its operation-specific admission policy. Public NemoClaw lifecycle admission can accept either host.docker.storage_compatible or host.docker.storage_remediation_available. When remediation is available, host.docker.storage_compatible remains absent. If host.docker.storage_incompatible is the sole blocking finding and host.docker.storage_remediation_available is present, host probe publishes status supported and exit code 0. The public report retains host.docker.storage_incompatible as a warning. Any other blocking or fatal finding prevents this public projection. The public status indicates a supported remediation path, not that the current Docker storage configuration is compatible. The remediation capability does not prove that a later image build or gateway attachment succeeds. Use these storage capabilities when the lifecycle may create or recreate a gateway. Gateway attachment is a separate readiness decision.

Interpret platform qualification

Platform checks report stable capabilities and qualifications for the detected host. Each capability uses present, absent, or unknown.

If the combined platform capability is absent and no more specific platform qualification finding applies, the blocking host.platform.unsupported finding identifies an unsupported host and runtime combination.

The report adds host.platform.wsl, host.platform.dgx_spark, host.platform.n1x, or host.platform.dgx_station qualifications when those platforms apply. For WSL, Docker Desktop is qualified, native Docker is unqualified, and an unrecognized reachable runtime is unknown. The host.platform.wsl_gpu_passthrough capability is present only after the Docker Desktop proof passes. It is absent when the proof fails or the host has no NVIDIA GPU, and unknown when the proof cannot run conclusively. The read-only host probe command does not pull or start the container-backed WSL GPU proof, so a host that needs that proof reports this capability as unknown. Onboarding can run the bounded proof only after its current host and gateway readiness checks admit the run.

DGX Station qualification fails closed. The host.platform.dgx_station capability is present only when the host runs Linux ARM64 on Ubuntu 24.04, reports an effective NVIDIA GPU, and the product identity, an exact display-class PCI device with NVIDIA vendor ID (0x10de) and GB300 device ID (0x31c2 or 0x31c3), and the software profile all qualify. If /etc/dgx-release is absent, NemoClaw uses the qualified generic-ubuntu profile. If the marker exists, NemoClaw reads it only when it is a nonempty regular non-symlink file of at most 4096 bytes, owned by UID and GID 0, and not writable by group or other users. Invalid marker metadata, invalid contents, or another known mismatch produce an unqualified qualification and the blocking host.platform.dgx_station_unqualified finding. An unreadable marker or missing required OS or PCI evidence produces an unknown qualification and the blocking host.platform.dgx_station_inconclusive finding. Both outcomes prevent host.platform.supported from becoming present. When available, bounded Station identity appears under evidence ID host.platform.identity.

N1x identity qualification also fails closed. The host.platform.n1x capability is present only when the host runs Linux ARM64, reports an effective NVIDIA GPU, and both identity sources qualify. /etc/fastos-release must be a regular file of 1 through 4,096 bytes that is owned by UID and GID 0, is not a symbolic link, grants no group or world write access, contains no NUL or carriage-return byte, and contains exactly one NAME="N1x FASTOS" line. NemoClaw parses the marker as inert text and does not pin its VERSION value. A display-class PCI device must report NVIDIA vendor ID 0x10de and device ID 0x2e2a. Generic DMI values do not satisfy either requirement.

A matching identity produces a qualified host.platform.n1x qualification, but host.platform.supported remains absent while N1x is Deferred. The blocking host.platform.n1x_validation_pending finding records the remaining physical NemoClaw Express E2E gate. Explicit NEMOCLAW_PROVIDER=install-vllm intent, including acceptance of the installer N1x preview prompt, lets onboarding waive only that finding after host.platform.n1x is present. The read-only host probe report remains incompatible and does not apply that onboarding exception.

Invalid marker metadata, invalid or ambiguous contents, the wrong PCI identity, the wrong architecture, or an unavailable NVIDIA GPU produces an unqualified qualification and the blocking host.platform.n1x_unqualified finding. Unreadable marker or PCI evidence produces an unknown qualification and the blocking host.platform.n1x_inconclusive finding. Neither finding can be waived by managed-vLLM intent. Bounded evidence appears under host.platform.identity with product, nvidiaPlatform, n1xCandidate, n1xFastOsMarker, and n1xPciGpu fields.

Interpret NVIDIA GPU Integration

GPU readiness distinguishes Jetson/Tegra Docker runtime integration from CDI-based NVIDIA GPU integration on other Linux hosts.

Jetson/Tegra detection can use platform firmware and device evidence even when nvidia-smi is unavailable. Its remediation configures the Docker NVIDIA runtime and does not instruct the user to generate CDI files. An explicit CPU-only onboarding run can waive GPU integration findings for that run; host probe still reports the observed host state.

Interpret Gateway Readiness

Gateway readiness establishes one lifecycle authority before onboarding can create or change managed resources. The report covers both NemoClaw-managed and externally supervised gateways.

The gateway observations use these stable IDs:

Each gateway capability uses present, absent, or unknown:

Use finding IDs to handle gateway failures without parsing summaries:

The report includes bounded evidence for the resolved owner and applicable attachment, port, collection, or stale-observation failures. When NemoClaw resolves the complete listener set, port-conflict evidence lists every listener by process name and PID, or by PID when no name is available. A stop command targets only listeners that fail ownership verification. NemoClaw does not provide a stop command for a verified managed listener. If NemoClaw resolves no listener, the diagnostic provides an lsof inspection command. It omits the gateway state directory, removes process environments, redacts credential-shaped content, bounds diagnostic length, and renders control characters visibly.

Managed gateway metadata is reusable only when its endpoint is bound to loopback on the configured gateway port. A legacy Docker proxy is accepted only when the active cluster container and its published host port establish the same target. For a direct Linux host-process gateway, version comparison runs only against an independently resolved binary whose exact path matches the listener’s kernel-backed executable identity. For a package service, the validated systemd ExecStart or official Homebrew formula binary must match the live executable before NemoClaw runs that trusted binary’s version command. NemoClaw samples the listener executable on both sides of identity checks and samples an external listener on both sides of its health request. A PID, executable, service, or listener change during that interval makes the result inconclusive instead of combining evidence from different processes. A service PID with missing or ambiguous executable evidence produces unknown version compatibility instead of comparing an unrelated CLI sibling.

An externally supervised declaration is authoritative. NemoClaw validates its endpoint, supervisor, listener identity, port, and required capabilities. NemoClaw does not start, stop, replace, or use a standalone fallback for that gateway. An owner mismatch, multiple listeners, or missing identity evidence blocks onboarding before managed lifecycle effects.

Understand Onboarding Admission

Onboarding consumes the same stable host and gateway entities as host probe. It applies an onboarding policy instead of treating the public report status as the only decision.

Fresh onboarding and authoritative rebuilds use this order:

1. Resolve and validate gateway authority.
2. Collect canonical host and gateway facts and reject blocking findings or unknown required capabilities.
3. On a resumed agent change, retain the old router and durable provider state until the full preflight phase succeeds; only then stop the old router and commit the projected agent state.
4. Apply only an explicitly permitted host remediation, if required, and replace the earlier observations.
5. Run a bounded WSL GPU proof when required, then revalidate live host and gateway facts.
6. Validate the effective GPU configuration before Docker bridge and container DNS probes that can start a short-lived container.
7. Install or upgrade OpenShell when required. A successful install can change gateway authority only from managed standalone to packaged-service. NemoClaw records that transition before later effects.
8. Revalidate gateway authority immediately before gateway selection, recovery, reconciliation, or other lifecycle effects.

The readiness gate runs before model-router cleanup, provider selection, credential registration, policy changes, image builds, or sandbox lifecycle effects. Host and gateway observations have a 30-second reuse window. If collection itself takes too long, onboarding rejects the stale composite instead of assigning a fresh timestamp to old facts.

The policy permits only these narrow exceptions:

• An explicit CPU-only sandbox mode makes NVIDIA GPU passthrough findings irrelevant to that run.
• The experimental portable profile can prepare its rootless runtime after an initial admission check.
• A NemoClaw-managed gateway can apply the documented Docker storage remediation when the report says it is available.
• A NemoClaw-managed gateway can reconcile version drift after its ownership and port checks pass.
• An explicit runtime path that does not use the standard Docker driver can admit its documented runtime exception.

The portable profile discards its earlier host and gateway observations after preparation. It collects both again before the runtime probes or later lifecycle effects. No other blocking finding or unknown required capability is waived.

Resume does not trust a cached preflight result for live host or gateway facts. It collects both again before a container-backed WSL GPU proof, GPU validation, or bridge and DNS probes. Explicit CPU-only intent skips the WSL GPU proof. The gateway phase validates authority again immediately before managed reconciliation or external attachment.

Authoritative rebuild preflight pins read-only probes to the recorded gateway without selecting, starting, or recovering it. Immediately before source deletion, the rebuild journal requires the complete gateway authority to match that preflight handoff. It accepts only one managed lifecycle change: a recorded package-managed service that now resolves as the standalone gateway. It carries the journaled authority into replacement onboarding. Refer to Declare the OpenShell Gateway Lifecycle Authority for the complete exception contract. Gateway recovery remains after the canonical readiness gate.

For external supervision, onboarding skips managed gateway selection, reuse refresh, cleanup, start, stop, replace, and standalone fallback paths. It attaches only after the current external authority passes the readiness checks.

Distinguish Sandbox Doctor

nemo-deepagents <name> doctor remains a separate diagnostic workflow for an existing sandbox and its dependencies. Its report and exit behavior are not the system readiness JSON contract. An agent runtime can expose an explicit doctor --fix repair mode, while host probe cannot change state.

The Docker host check in doctor and the system readiness report share the same daemon-reachability semantics. Both require positive server-version evidence from JSON docker info output. They reject an exit-zero response that contains empty or error-only daemon data.

Understand the Read-Only Boundary

host probe observes the host and does not run remediation. Repeated runs do not change filesystem, service, Docker image or container, gateway, provider, credential, policy, or sandbox state. Read-only child processes receive a replacement environment containing only exact system variables, the selected OpenShell gateway, its validated local TLS directory when present, and a supported local Unix Docker socket when configured. Ambient provider, OpenShell, sandbox, and gateway credentials are not forwarded to those children. A future command that changes the host must use a separate mutating mode. That mode cannot run with --json probing.

The public report removes process environments and unrecognized fields from internal probe results. It redacts token-shaped values and credential-bearing URLs. It also limits finding summaries and command evidence before either presentation receives the report. It rejects a report that claims mutation and retains every blocking or fatal finding at the bounded public-report boundary.