fix(onboard): clarify post-install next steps and add dashboard-url command

docs/get-started/quickstart-hermes.mdx

@@ -88,16 +88,27 @@ Hermes exposes an OpenAI-compatible API on port `8642`, not a browser dashboard.
 
 ```text
 ──────────────────────────────────────────────────
-Sandbox      my-hermes (Landlock + seccomp + netns)
-Model        nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoints)
-──────────────────────────────────────────────────
-Run:         nemohermes my-hermes connect
-Status:      nemohermes my-hermes status
-Logs:        nemohermes my-hermes logs --follow
+NemoHermes is ready
+
+Sandbox:  my-hermes
+Model:    nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoints)
+
+Access
+
+  Hermes Agent OpenAI-compatible API
+  Port 8642 must be forwarded before connecting.
+  http://127.0.0.1:8642/v1
+
+Terminal:
+  nemohermes my-hermes connect
+
+Manage later
 
-Hermes Agent OpenAI-compatible API
-Port 8642 must be forwarded before connecting.
-http://127.0.0.1:8642/v1
+  Status:      nemohermes my-hermes status
+  Logs:        nemohermes my-hermes logs --follow
+  Model:       nemohermes inference set --model <model> --provider <provider> --sandbox my-hermes
+  Policies:    nemohermes my-hermes policy-add
+  Credentials: nemohermes credentials reset <KEY> && nemohermes onboard
 ──────────────────────────────────────────────────
 ```
 

docs/get-started/quickstart.mdx

@@ -294,17 +294,31 @@ The example below shows the result if you picked an OpenAI-compatible endpoint d
 
 ```text
 ──────────────────────────────────────────────────
-Sandbox      my-gpt-claw (Landlock + seccomp + netns)
-Model        openai/openai/gpt-5.5 (Other OpenAI-compatible endpoint)
-──────────────────────────────────────────────────
-Run:         nemoclaw my-gpt-claw connect
-Status:      nemoclaw my-gpt-claw status
-Logs:        nemoclaw my-gpt-claw logs --follow
-──────────────────────────────────────────────────
+NemoClaw is ready
+
+Sandbox:  my-gpt-claw
+Model:    openai/openai/gpt-5.5 (Other OpenAI-compatible endpoint)
+
+Start chatting
 
-To change settings later:
-  Model:       nemoclaw inference get
-               nemoclaw inference set --model <model> --provider <provider> --sandbox my-gpt-claw
+  Browser:
+    http://127.0.0.1:18789/
+
+  Terminal:
+    nemoclaw my-gpt-claw connect
+    then run: openclaw tui
+
+Authenticated dashboard URL, if needed:
+  nemoclaw my-gpt-claw dashboard-url --quiet
+
+Manage later
+
+  Status:      nemoclaw my-gpt-claw status
+  Logs:        nemoclaw my-gpt-claw logs --follow
+  Model:       nemoclaw inference set --model <model> --provider <provider> --sandbox my-gpt-claw
+  Policies:    nemoclaw my-gpt-claw policy-add
+  Credentials: nemoclaw credentials reset <KEY> && nemoclaw onboard
+──────────────────────────────────────────────────
 
 [INFO]  === Installation complete ===
 ```
@@ -321,34 +335,25 @@ The onboard wizard starts a background port forward to the sandbox dashboard, th
 The default host port is `18789`.
 If that port is already taken, NemoClaw uses the next free dashboard port, such as `18790`, and prints that port in the final URL.
 If the chosen port becomes occupied after the sandbox build starts, onboarding rolls back the newly-created sandbox and asks you to retry instead of printing an unreachable dashboard URL.
-The gateway token is redacted from displayed output; retrieve it explicitly when the browser asks for authentication.
+The gateway token is not printed in the install transcript.
+If authentication is required, use the `dashboard-url --quiet` command to print a complete URL explicitly.
 
 ```text
-──────────────────────────────────────────────────
-OpenClaw UI (auth token redacted from displayed URLs)
-Port 18790 must be forwarded before opening these URLs.
-Dashboard: http://127.0.0.1:18790/
-Token:       nemoclaw my-gpt-claw gateway-token --quiet
-             append  #token=<token> locally if the browser asks for auth.
-──────────────────────────────────────────────────
+nemoclaw my-gpt-claw dashboard-url --quiet
 ```
 
 Open the dashboard URL in your browser.
-If the browser asks for authentication, run the printed `gateway-token --quiet` command and append `#token=<token>` locally.
-Treat the token like a password.
+If the browser asks for authentication, run `nemoclaw my-gpt-claw dashboard-url --quiet` and open the returned URL.
+Treat the authenticated URL like a password.
 
 ### Chat with the Agent from the Terminal
 
 Connect to the sandbox and use the OpenClaw CLI.
 
 ```bash
 nemoclaw my-assistant connect
-```
-
-In the sandbox shell, send a single message and print the response.
-
-```bash
-openclaw agent --agent main --local -m "hello" --session-id test
+# inside the sandbox:
+openclaw tui
 ```
 
 ## Next Steps

docs/reference/commands.mdx

@@ -432,10 +432,33 @@ If one log source is unavailable, NemoClaw prints a warning and keeps reading th
 $ nemoclaw my-assistant logs [--follow] [--tail <lines>|-n <lines>] [--since <duration>]
 ```
 
+### `nemoclaw <name> dashboard-url`
+
+Print the authenticated OpenClaw dashboard URL for a running sandbox.
+Use this when you are on a remote machine, using an SSH or reverse tunnel, or need a complete URL for a browser session.
+
+```console
+$ nemoclaw my-assistant dashboard-url
+$ nemoclaw my-assistant dashboard-url --quiet
+```
+
+The default output includes a label and a warning.
+Pass `--quiet` or `-q` to print only the URL to stdout so scripts can capture it:
+
+```console
+$ URL=$(nemoclaw my-assistant dashboard-url --quiet)
+```
+
+<Warning>
+Treat the authenticated dashboard URL like a password.
+Do not log it, share it, or commit it to version control.
+</Warning>
+
 ### `nemoclaw <name> gateway-token`
 
 Print the OpenClaw gateway auth token for a running sandbox to stdout.
-The token is required by `openclaw tui` and the OpenClaw dashboard URL, but onboarding only prints it once.
+The token is required by `openclaw tui` and the OpenClaw dashboard URL.
+Use `dashboard-url` for browser access; use `gateway-token` only when automation needs the raw token.
 Pipe it into automation or capture it into an environment variable:
 
 ```console

scripts/install.sh

@@ -466,41 +466,22 @@ print_done() {
   printf "  ${C_GREEN}${C_BOLD}%s${C_RESET}  ${C_DIM}(%ss)${C_RESET}\n" "$_CLI_DISPLAY" "$elapsed"
   printf "\n"
   if [[ "$ONBOARD_RAN" == true ]]; then
-    local sandbox_name agent_name
-    sandbox_name="$(resolve_default_sandbox_name)"
+    local agent_name
     agent_name="$(resolve_onboarded_agent)"
     if [[ "$_needs_cli_refresh" == true ]]; then
       printf "  ${C_YELLOW}%s installed, but this shell needs PATH refresh before '%s' will run.${C_RESET}\n" "$_CLI_DISPLAY" "$_CLI_BIN"
       printf "  ${C_DIM}Onboarding completed; refresh PATH before using the CLI from this terminal.${C_RESET}\n"
+      printf "\n"
+      printf "  ${C_GREEN}For this terminal:${C_RESET}\n"
+      print_cli_path_refresh_actions
     else
       if [[ "$agent_name" == "openclaw" || -z "$agent_name" ]]; then
         printf "  ${C_GREEN}Your OpenClaw Sandbox is live.${C_RESET}\n"
       else
         printf "  ${C_GREEN}Your %s Sandbox is live.${C_RESET}\n" "$(agent_display_name "$agent_name")"
       fi
-      printf "  ${C_DIM}Sandbox in, break things, and tell us what you find.${C_RESET}\n"
-    fi
-    printf "\n"
-    printf "  ${C_GREEN}Next:${C_RESET}\n"
-    if [[ "$_needs_cli_refresh" == true ]]; then
-      print_cli_path_refresh_actions
-    else
-      printf "  %s$%s source %s\n" "$C_GREEN" "$C_RESET" "$(detect_shell_profile)"
+      printf "  ${C_DIM}Use the Start chatting section above for browser and terminal options.${C_RESET}\n"
     fi
-    printf "  %s$%s %s %s connect\n" "$C_GREEN" "$C_RESET" "$_CLI_BIN" "$sandbox_name"
-    local agent_cmd
-    case "$agent_name" in
-      hermes)
-        agent_cmd="hermes"
-        ;;
-      "" | openclaw)
-        agent_cmd="openclaw tui"
-        ;;
-      *)
-        agent_cmd="$agent_name"
-        ;;
-    esac
-    printf "  %ssandbox@%s$%s %s\n" "$C_GREEN" "$sandbox_name" "$C_RESET" "$agent_cmd"
   elif [[ "$NEMOCLAW_READY_NOW" == true ]]; then
     if [[ "$_needs_cli_refresh" == true ]]; then
       printf "  ${C_YELLOW}%s CLI is installed, but this shell needs PATH refresh before '%s' will run.${C_RESET}\n" "$_CLI_DISPLAY" "$_CLI_BIN"

src/commands/sandbox/dashboard-url.ts

@@ -0,0 +1,106 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Args } from "@oclif/core";
+import { quietFlag } from "../../lib/cli/common-flags";
+import { NemoClawCommand } from "../../lib/cli/nemoclaw-oclif-command";
+import { runCapture } from "../../lib/runner";
+import {
+  DashboardUrlCommandError,
+  runDashboardUrlCommand,
+} from "../../lib/dashboard-url-command";
+import type { SandboxEntry } from "../../lib/state/registry";
+
+type DashboardUrlRuntimeBridge = {
+  fetchGatewayAuthTokenFromSandbox: (sandboxName: string) => string | null;
+  getSandbox: (sandboxName: string) => Pick<SandboxEntry, "agent" | "dashboardPort"> | null;
+  getAccessUrl?: (port: number) => string | null;
+};
+
+let runtimeBridgeFactory = (): DashboardUrlRuntimeBridge => {
+  const onboard = require("../../lib/onboard") as Pick<
+    DashboardUrlRuntimeBridge,
+    "fetchGatewayAuthTokenFromSandbox"
+  >;
+  const registry = require("../../lib/state/registry") as {
+    getSandbox: (name: string) => SandboxEntry | null;
+  };
+  const dashboardAccess = require("../../lib/onboard/dashboard-access") as typeof import("../../lib/onboard/dashboard-access");
+  return {
+    fetchGatewayAuthTokenFromSandbox: onboard.fetchGatewayAuthTokenFromSandbox,
+    getSandbox: (sandboxName: string) => {
+      try {
+        return registry.getSandbox(sandboxName);
+      } catch {
+        return null;
+      }
+    },
+    getAccessUrl: (port: number) =>
+      dashboardAccess.buildDashboardChain(`http://127.0.0.1:${port}`, {
+        runCapture,
+      }).accessUrl,
+  };
+};
+
+export function setDashboardUrlRuntimeBridgeFactoryForTest(
+  factory: () => DashboardUrlRuntimeBridge,
+): void {
+  runtimeBridgeFactory = factory;
+}
+
+function getRuntimeBridge(): DashboardUrlRuntimeBridge {
+  return runtimeBridgeFactory();
+}
+
+export default class DashboardUrlCliCommand extends NemoClawCommand {
+  static id = "sandbox:dashboard-url";
+  static strict = true;
+  static summary = "Print the authenticated OpenClaw dashboard URL";
+  static description = "Print the authenticated OpenClaw dashboard URL for a running sandbox.";
+  static usage = ["<name> [--quiet|-q]"];
+  static examples = [
+    "<%= config.bin %> sandbox dashboard-url alpha",
+    "<%= config.bin %> sandbox dashboard-url alpha --quiet",
+  ];
+  static args = {
+    sandboxName: Args.string({
+      name: "sandbox",
+      description: "Sandbox name",
+      required: true,
+    }),
+  };
+  static flags = {
+    quiet: quietFlag("Print only the URL"),
+  };
+
+  public async run(): Promise<void> {
+    const { args, flags } = await this.parse(DashboardUrlCliCommand);
+    process.stdout.once("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "EPIPE") {
+        this.setExitCode(0);
+        return;
+      }
+      throw err;
+    });
+
+    const runtime = getRuntimeBridge();
+    try {
+      runDashboardUrlCommand(
+        args.sandboxName,
+        { quiet: flags.quiet === true },
+        {
+          fetchToken: runtime.fetchGatewayAuthTokenFromSandbox,
+          getSandbox: runtime.getSandbox,
+          getAccessUrl: runtime.getAccessUrl,
+        },
+      );
+      this.setExitCode(0);
+    } catch (error) {
+      if (error instanceof DashboardUrlCommandError) {
+        this.failWithLines(error.lines, error.exitCode);
+        return;
+      }
+      throw error;
+    }
+  }
+}

src/commands/simple-global-oclif-adapters.test.ts

@@ -15,6 +15,17 @@ const mocks = vi.hoisted(() => {
       this.exitCode = exitCode;
     }
   }
+  class DashboardUrlCommandError extends Error {
+    lines: readonly string[];
+    exitCode: number;
+
+    constructor(lines: string | readonly string[], exitCode = 1) {
+      const normalized = Array.isArray(lines) ? lines : [lines];
+      super(normalized.join("\n"));
+      this.lines = normalized;
+      this.exitCode = exitCode;
+    }
+  }
 
   return {
     buildVersionedUninstallUrl: vi.fn((version: string) => `https://example.test/${version}/uninstall.sh`),
@@ -25,6 +36,7 @@ const mocks = vi.hoisted(() => {
     resolveOpenshell: vi.fn(() => "/usr/bin/openshell"),
     runDebugCommandWithOptions: vi.fn(),
     runDeployAction: vi.fn().mockResolvedValue(undefined),
+    runDashboardUrlCommand: vi.fn(() => undefined),
     runGatewayTokenCommand: vi.fn(() => undefined),
     runStartCommand: vi.fn().mockResolvedValue(undefined),
     runStopCommand: vi.fn(),
@@ -34,6 +46,7 @@ const mocks = vi.hoisted(() => {
     spawnSync: vi.fn(),
     startAll: vi.fn(),
     stopAll: vi.fn(),
+    DashboardUrlCommandError,
     GatewayTokenCommandError,
   };
 });
@@ -47,6 +60,10 @@ vi.mock("../lib/gateway-token-command", () => ({
   GatewayTokenCommandError: mocks.GatewayTokenCommandError,
   runGatewayTokenCommand: mocks.runGatewayTokenCommand,
 }));
+vi.mock("../lib/dashboard-url-command", () => ({
+  DashboardUrlCommandError: mocks.DashboardUrlCommandError,
+  runDashboardUrlCommand: mocks.runDashboardUrlCommand,
+}));
 vi.mock("../lib/actions/global", () => ({
   runDeployAction: mocks.runDeployAction,
   showRootHelp: mocks.showRootHelp,
@@ -68,6 +85,7 @@ vi.mock("../lib/core/version", () => ({ getVersion: mocks.getVersion }));
 
 import DebugCliCommand from "./debug";
 import DeployCliCommand from "./deploy";
+import DashboardUrlCliCommand, { setDashboardUrlRuntimeBridgeFactoryForTest } from "./sandbox/dashboard-url";
 import GatewayTokenCliCommand, { setGatewayTokenRuntimeBridgeFactoryForTest } from "./sandbox/gateway/token";
 import DeprecatedStartCommand from "./start";
 import DeprecatedStopCommand from "./stop";
@@ -127,6 +145,28 @@ describe("simple global oclif adapters", () => {
     );
   });
 
+  it("maps dashboard-url flags to the dashboard URL action", async () => {
+    const getSandbox = vi.fn(() => ({ agent: "openclaw", dashboardPort: 18789 }));
+    const getAccessUrl = vi.fn(() => "http://127.0.0.1:18789");
+    setDashboardUrlRuntimeBridgeFactoryForTest(() => ({
+      fetchGatewayAuthTokenFromSandbox: mocks.fetchGatewayAuthTokenFromSandbox,
+      getSandbox,
+      getAccessUrl,
+    }));
+
+    await DashboardUrlCliCommand.run(["alpha", "--quiet"], rootDir);
+
+    expect(mocks.runDashboardUrlCommand).toHaveBeenCalledWith(
+      "alpha",
+      { quiet: true },
+      expect.objectContaining({
+        fetchToken: mocks.fetchGatewayAuthTokenFromSandbox,
+        getSandbox,
+        getAccessUrl,
+      }),
+    );
+  });
+
   it("uses process.exitCode (no @oclif/core ExitError) when the gateway-token action fails", async () => {
     // NCQ #3180: legacy dispatch did not catch the @oclif/core ExitError
     // thrown by this.exit(1), surfacing a raw JS stack trace to the user.