Reference

Choose Between NemoClaw and OpenShell CLIs

View as Markdown

NemoClaw uses two host-side CLIs. Use nemo-deepagents for NemoClaw-managed workflows. Use openshell when you need a lower-level OpenShell operation that NemoClaw intentionally leaves available.

Rule of Thumb

If the task changes how NemoClaw creates, rebuilds, preserves, or configures a sandbox, start with nemo-deepagents.

If the task inspects or changes the live OpenShell gateway, TUI, raw policy, port forwarding, inference route, or sandbox file transfer, use openshell.

Do not create or recreate NemoClaw-managed sandboxes directly with openshell sandbox create unless you intend to manage OpenShell yourself. Run nemo-deepagents onboard afterward if you need to return to a NemoClaw-managed environment.

Use nemo-deepagents For NemoClaw Workflows

Use nemo-deepagents for operations where NemoClaw adds product-specific state, safety checks, backup behavior, credential handling, or agent configuration.

  • Install, onboard, or recreate a NemoClaw sandbox:

    $nemo-deepagents onboard
    $nemo-deepagents onboard --fresh --name <sandbox-name> --recreate-sandbox

Use --resume only when you are recovering an interrupted onboarding session. For a completed sandbox, use --fresh --name <sandbox-name> --recreate-sandbox when you need NemoClaw to recreate it.

  • List, connect to, check, or delete NemoClaw-managed sandboxes:

    $nemo-deepagents list
    $nemo-deepagents my-assistant connect
    $nemo-deepagents my-assistant status
    $nemo-deepagents my-assistant logs --follow
    $nemo-deepagents my-assistant destroy

  • Rebuild or upgrade while preserving workspace state:

    $nemo-deepagents my-assistant rebuild
    $nemo-deepagents upgrade-sandboxes --check

  • Snapshot, restore, or mount sandbox state:

    $nemo-deepagents my-assistant snapshot create --name before-change
    $nemo-deepagents my-assistant snapshot restore before-change
    $nemo-deepagents my-assistant share mount

  • Add or remove NemoClaw policy presets:

    $nemo-deepagents my-assistant policy-add pypi --yes
    $nemo-deepagents my-assistant policy-list
    $nemo-deepagents my-assistant policy-remove pypi --yes

  • Manage NemoClaw credentials, diagnostics, and cleanup:

    $nemo-deepagents credentials list
    $nemo-deepagents credentials reset nvidia-prod
    $nemo-deepagents debug --sandbox my-assistant
    $nemo-deepagents gc --dry-run

Use openshell For OpenShell Operations

Use openshell when the docs explicitly call for a live OpenShell gateway operation or when you need a lower-level view beneath the NemoClaw wrapper.

  • Open the OpenShell TUI for network approvals and live activity:

    $openshell term

  • Manage service port forwards:

    $openshell forward start --background <port> <sandbox-name>
    $openshell forward list

  • Inspect the underlying sandbox state:

    $openshell sandbox list
    $openshell sandbox get <sandbox-name>
    $openshell logs <sandbox-name> -n 20
    $openshell doctor check

  • Move files or run raw one-off commands when you intentionally want to bypass NemoClaw’s sandbox registry and wrappers:

    $openshell sandbox upload <sandbox-name> ./local-file /sandbox/
    $openshell sandbox download <sandbox-name> /sandbox/output ./output
    $openshell sandbox exec -n <sandbox-name> -- env | grep '^HOME='

  • Merge a single endpoint into the live OpenShell policy:

    $openshell policy update <sandbox-name> --add-endpoint api.example.com:443:read-only:rest:enforce

  • Inspect or replace raw OpenShell policy:

    Requires OpenShell 0.0.72+ for the round-trippable policy get --base and policy set --wait syntax.

    $# shellcheck shell=bash
    $# Source-of-truth review:
    $# invalidState: OpenShell 0.0.72 policy get --base emits metadata before the --- YAML header.
    $# sourceBoundary: OpenShell CLI output is owned by the separate OpenShell project.
    $# whyNotSourceFix: NemoClaw pins OpenShell but cannot change that upstream formatter here.
    $# regressionTest: test/policy-roundtrip-docs.test.ts validates this shared docs pattern.
    $# removalCondition: remove this pipeline after pinned OpenShell emits clean raw YAML.
    $tmp_policy=$(mktemp)
    $openshell policy get --base <sandbox-name> \
    >  | awk 'found { print } /^---$/ { found = 1 } END { if (!found) exit 1 }' \
    >  > "$tmp_policy" \
    >  && grep -q '^version:' "$tmp_policy" \
    >  && grep -q '^network_policies:' "$tmp_policy" \
    >  && mv "$tmp_policy" current-policy.yaml

    Edit or review current-policy.yaml, then apply it:

    $openshell policy set --policy current-policy.yaml --wait <sandbox-name>

openshell policy update merges specific endpoint and rule changes into the live sandbox policy. openshell policy set replaces the live policy with the file you provide. For normal NemoClaw network access changes, prefer nemo-deepagents <name> policy-add so NemoClaw preserves presets and records the change for rebuilds.

Common Decisions

This section covers common decisions when using the NemoClaw CLI and the OpenShell CLI.

First Setup or Full Recreate

Use nemo-deepagents onboard. It starts the OpenShell gateway when needed, registers providers, builds the selected agent sandbox image, applies NemoClaw policy choices, and creates the sandbox.

Avoid running openshell gateway start --recreate or openshell sandbox create directly for NemoClaw-managed sandboxes. Those commands do not update NemoClaw’s registry, session metadata, workspace-preservation flow, or agent-specific configuration.

Connect to the Sandbox

Use nemo-deepagents <name> connect for an interactive NemoClaw sandbox shell. It waits for readiness, handles stale SSH host keys after gateway restarts, and prints agent-specific hints.

Use openshell sandbox connect <name> only when you intentionally want the raw OpenShell connection path.

For a one-off command in a NemoClaw-managed sandbox, use nemo-deepagents <name> exec instead of opening an interactive shell. It resolves the sandbox by its NemoClaw registry name and runs through the standard NemoClaw CLI surface. The command executes as the sandbox user with HOME=/sandbox inside the provisioned sandbox, where the agent configuration, inference routing, and policy state are already in place.

$nemo-deepagents my-assistant exec -- cat /tmp/gateway.log

Use openshell sandbox exec for the raw OpenShell execution path, such as when you address a sandbox by its gateway name or intentionally bypass the NemoClaw CLI and registry.

$openshell sandbox exec -n my-assistant -- cat /tmp/gateway.log

Check Health or Logs

Use nemo-deepagents <name> status and nemo-deepagents <name> logs first. They combine NemoClaw registry data, OpenShell state, selected agent process health, inference health, policy details, and messaging-channel warnings for that sandbox. Use nemo-deepagents status only for the global all-sandbox and host-service overview.

Use openshell sandbox list, openshell sandbox get, openshell logs <name> -n 20, or openshell doctor check when debugging lower-level OpenShell behavior. When using openshell logs directly, -n <lines> controls the line count; use --tail only when you want live OpenShell log streaming.

Approve Blocked Network Requests

Use openshell term. The OpenShell TUI owns live network activity and operator approval prompts.

Approved endpoints are session-scoped unless you also add them to the policy through a NemoClaw preset or raw OpenShell policy update.

Change Models or Providers

For Deep Agents sandboxes, prefer a fresh recreate when you need to change the provider or model. The managed dcode configuration is written under /sandbox/.deepagents during onboarding, so the recreate path keeps the OpenShell route and the sandbox config aligned while the Deep Agents runtime switch path is still being hardened.

$nemo-deepagents onboard --fresh --name <sandbox-name> --recreate-sandbox

For a build-time agent setting change, rerun onboarding so the sandbox configuration is recreated consistently:

$nemo-deepagents onboard --fresh --name <sandbox-name> --recreate-sandbox

Verify either path with:

$nemo-deepagents <name> status

Update Network Policy

Use nemo-deepagents <name> policy-add or policy-remove for NemoClaw presets and custom preset files. NemoClaw merges the new policy with the live policy and reapplies presets during rebuilds.

Use openshell policy update for precise live endpoint or REST rule changes. Use openshell policy get --base <name> and openshell policy set --policy <file> --wait <name> only when you need to edit and replace the round-trippable base policy. Use --full only to inspect the effective policy, including provider-composed rules.

Move Workspace Files

Use nemo-deepagents <name> snapshot create, snapshot restore, or share mount for normal workspace preservation and editing.

Use openshell sandbox upload and openshell sandbox download for manual file copies when you need exact control over source and destination paths.