fix(cli): show SSH port-forward hint for remote dashboard access (#5925)

[atulya-singh]

Summary

When NemoClaw runs inside an SSH session, the dashboard URL binds to 127.0.0.1 on the remote host and is unreachable from the operator's workstation browser without a port forward. The post-onboard summary and dashboard-url output now print a copy-pastable ssh -L <port>:127.0.0.1:<port> <user>@<host> example, and the Quickstart and remote-GPU deploy docs cross-reference the same command.

Related Issue

Fixes #5925

Changes

• Add pure helper src/lib/onboard/ssh-forward-hint.ts:
  • isSshSession() detects SSH_CONNECTION / SSH_CLIENT / SSH_TTY.
  • buildSshForwardHintLines() derives the host from the SSH_CONNECTION server-IP field and the user from USER/LOGNAME, returning a copy-pastable ssh -L block. Returns null outside an SSH session or when the dashboard already binds a routable address (WSL fallback, NEMOCLAW_DASHBOARD_BIND=0.0.0.0). Unsafe usernames fall back to <user>; an unknown host falls back to <host>.
• src/lib/dashboard-url-command.ts: append the hint to non-quiet output (both token and session-auth paths); suppressed under --quiet so scripted consumers still get exactly one line.
• src/lib/onboard/dashboard.ts: printDashboard shows the hint in the post-onboard "is ready" summary (covers OpenClaw and agent dashboards).
• Docs: new "Open the Dashboard When You SSH'd into a Remote Host" subsection in docs/get-started/quickstart.mdx, and a copy-pastable ssh -L command in docs/deployment/deploy-to-remote-gpu.mdx (Remote Dashboard Access).
• Tests: ssh-forward-hint.test.ts (8 cases) plus 3 new dashboard-url-command.test.ts cases (hint over SSH, absent without SSH, suppressed under --quiet).

The hint only ever references loopback forwarding; it does not suggest binding to 0.0.0.0, and it points to the already-printed dashboard URL rather than reprinting the tokenized URL, so it does not duplicate the secret token.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Atulya Singh atulyarajsingh@gmail.com

Summary by CodeRabbit

• New Features
  • Added SSH port-forwarding guidance for accessing the dashboard when connected via SSH.
  • Dashboard onboarding and dashboard URL output can now show copy-pastable ssh -L instructions when forwarding is needed.
• Bug Fixes
  • Dashboard URL output now conditionally includes (or omits) the SSH forwarding hint based on SSH/session context and whether the dashboard URL is loopback-bound; quiet mode remains unchanged.
  • Improved, safer SSH-session detection and sanitization of rendered hint content.
• Documentation
  • Updated the remote GPU guide and quickstart with local workstation browser and ssh -L examples.
• Tests
  • Added coverage for SSH hint generation, session detection, and dashboard URL command behavior.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3da22a89-1743-4751-897a-ff8cc9737a6a

📥 Commits

Reviewing files that changed from the base of the PR and between f593b57 and ce1f066.

📒 Files selected for processing (2)

• docs/deployment/deploy-to-remote-gpu.mdx
• docs/get-started/quickstart.mdx

💤 Files with no reviewable changes (2)

• docs/get-started/quickstart.mdx
• docs/deployment/deploy-to-remote-gpu.mdx

---

📝 Walkthrough

Walkthrough

Adds SSH-session detection and copy-pastable ssh -L hint generation for dashboard access, wires it into dashboard-url and onboarding output, and updates quickstart and deployment docs with matching remote-SSH instructions.

Changes

SSH Port-Forward Hint

Layer / File(s)	Summary
SSH hint helper and tests src/lib/onboard/ssh-forward-hint.ts, src/lib/onboard/ssh-forward-hint.test.ts	New module exports isSshSession and buildSshForwardHintLines, sanitizes user and destination values, checks whether the access URL still needs forwarding, and returns formatted hint lines or null. Tests cover SSH detection, placeholder rendering, sanitization, custom formatting, and non-forwarding cases.
Dashboard URL command output src/lib/dashboard-url-command.ts, src/lib/dashboard-url-command.test.ts	DashboardUrlCommandDeps gains optional env, a local helper prints SSH hint lines when available, and both the plain URL and token-based paths call it before returning or logging the dashboard URL. Tests cover SSH-session output, session-auth behavior, no-hint output without SSH env, and quiet-mode suppression.
Onboarding dashboard output src/lib/onboard/dashboard.ts	OnboardDashboardDeps gains optional env, and printDashboard computes SSH hint lines from chain.port and chain.accessUrl before the existing “Manage later” output.
Quickstart and deployment docs docs/get-started/quickstart.mdx, docs/deployment/deploy-to-remote-gpu.mdx	Quickstart adds a remote-SSH dashboard subsection with loopback binding explanation and an ssh -L example. The deployment guide adds matching remote dashboard port-forwarding instructions and references the CLI output flow.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User as SSH user
  participant DashboardUrl as dashboard-url command
  participant Onboard as onboarding output
  participant Hint as buildSshForwardHintLines
  participant Env as process.env
  User->>DashboardUrl: run dashboard-url
  DashboardUrl->>Hint: port, accessUrl, env
  Hint->>Env: read SSH_* and USER
  Hint-->>DashboardUrl: hint lines or null
  DashboardUrl-->>User: dashboard URL + SSH hint

  User->>Onboard: complete onboarding
  Onboard->>Hint: port, accessUrl, env
  Hint-->>Onboard: hint lines or null
  Onboard-->>User: ready block + SSH hint

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 62.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding SSH port-forward hints for remote dashboard access.
Linked Issues check	✅ Passed	The CLI, onboarding output, Quickstart, and remote GPU docs now provide SSH port-forward guidance for remote-SSH users.
Out of Scope Changes check	✅ Passed	The added helper, tests, and documentation all support the remote dashboard access fix and stay within scope.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

src/lib/dashboard-url-command.test.ts (1)

88-138: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a non-quiet assertion for the session/none branch.

These cases only exercise the tokenized URL path. runDashboardUrlCommand now prints the SSH hint in the plain-URL branch too, but the visible session coverage is still quiet-only, so a regression there would slip through.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/dashboard-url-command.test.ts` around lines 88 - 138, The test
coverage for runDashboardUrlCommand is missing a non-quiet assertion for the
plain-URL path when no tokenized session is used, so add a case that exercises
the session/none branch with quiet false and verifies the SSH hint is printed
there too. Update the dashboard URL command tests around runDashboardUrlCommand
and makeSinks to assert the Remote access SSH hint appears in the non-quiet
plain-URL output, while keeping the quiet-mode behavior unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/deployment/deploy-to-remote-gpu.mdx`:
- Line 154: Split the combined sentence in the deployment guide into two
separate source lines to follow the one-sentence-per-line MDX rule. Update the
surrounding prose in the deployment section so the first sentence about running
nemoclaw over SSH and the command output stands alone, and the second sentence
about opening the dashboard URL on your workstation is on its own line.

In `@src/lib/onboard/dashboard.ts`:
- Around line 496-499: Pass env explicitly into buildSshForwardHintLines from
this OnboardDashboard flow instead of letting it read process.env implicitly.
Thread env through OnboardDashboardDeps here the same way dashboard-url already
does, and update the call site in the dashboard summary rendering so the SSH
hint stays deterministic and testable. Also make sure any related SSH hint or
detection helpers use the passed env argument rather than ambient shell state.

In `@src/lib/onboard/ssh-forward-hint.ts`:
- Around line 27-37: The helper serverAddressFromSshConnection should not derive
the SSH destination from SSH_CONNECTION, since it only exposes the remote socket
address and loses the original host, port, aliases, and ProxyJump details.
Update the ssh-forward-hint flow to return a placeholder unless the caller can
pass the original destination string explicitly, and keep
serverAddressFromSshConnection limited to fallback behavior rather than
constructing the ssh -L example target.

---

Nitpick comments:
In `@src/lib/dashboard-url-command.test.ts`:
- Around line 88-138: The test coverage for runDashboardUrlCommand is missing a
non-quiet assertion for the plain-URL path when no tokenized session is used, so
add a case that exercises the session/none branch with quiet false and verifies
the SSH hint is printed there too. Update the dashboard URL command tests around
runDashboardUrlCommand and makeSinks to assert the Remote access SSH hint
appears in the non-quiet plain-URL output, while keeping the quiet-mode behavior
unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e1935265-b6a6-458e-8355-ff9cab336012

📥 Commits

Reviewing files that changed from the base of the PR and between 4db5d5d and 9191002.

📒 Files selected for processing (7)

• docs/deployment/deploy-to-remote-gpu.mdx
• docs/get-started/quickstart.mdx
• src/lib/dashboard-url-command.test.ts
• src/lib/dashboard-url-command.ts
• src/lib/onboard/dashboard.ts
• src/lib/onboard/ssh-forward-hint.test.ts
• src/lib/onboard/ssh-forward-hint.ts

[wscurran]

✨ Thanks for adding the SSH port-forward hint for remote dashboard access. This fixes the missing copy-pastable ssh -L example for users running NemoClaw over SSH.

---

Related open issues:

• #5925 [All Platforms][CLI&UX] dashboard-url and post-onboard output print only the loopback URL — no copy-pastable SSH port-forward example for remote-SSH'd users

[cv]

Unresolved correctness issue: SSH_CONNECTION cannot recover the original user-facing destination across aliases, NAT, or ProxyJump, but the current hint presents the inferred socket IP as copy-pastable. Use unless an explicit original destination is supplied, and cover aliased and jump-host scenarios. Required CI and advisor also have not run.

[atulya-singh]

@cv thanks — addressed the correctness issue.

What changed

The hint no longer turns SSH_CONNECTION into the SSH destination. As you noted, its server-IP field is just the remote socket address and can't recover the destination the operator actually typed across an ~/.ssh/config alias, NAT, or ProxyJump, so presenting it as copy-pastable was wrong for exactly the sessions this feature targets.

• Host → <host> placeholder by default. A concrete host is only rendered when an explicit destination is supplied to buildSshForwardHintLines({ destination }); nothing is inferred from SSH_CONNECTION. sshDestinationFromConnection() and the DEFAULT_SSH_PORT constant are removed.
• Dropped the -p <port> flag — it came from the same untrusted SSH_CONNECTION field and would look authoritative next to a placeholder host.
• Username is kept (falling back to <user> when missing/unsafe): unlike the host, it's the effective remote login user and stays correct through NAT/ProxyJump. Net render: ssh -L 18790:127.0.0.1:18790 spark@<host>.

Test coverage for aliased / jump-host

Added cases asserting the socket IP never leaks — a NAT'd/aliased direct host and a private bastion-side (ProxyJump) target on a custom port both render spark@<host> with no IP and no -p. Also added explicit-destination-verbatim and unsafe-destination-fallback cases. Removed the now-invalid -p test.

Docs

deploy-to-remote-gpu.mdx no longer claims the CLI prints the "detected host" — it now states the host stays a <host> placeholder you substitute, and why.

Verified locally: ssh-forward-hint + dashboard-url-command suites, the full src/lib/onboard/ CLI suite (1643 passing), npm run typecheck:cli, Biome, and npm run docs (0 errors).

On the CI/advisor note — those required jobs are gated behind copy-pr-bot maintainer vetting and haven't been able to run on this fork PR yet; they should execute once vetted.

Addressed on current head ce1f066: the hint always uses unless an explicit destination is available, and alias/NAT/ProxyJump regression cases cover the original correctness concern. All 32 checks are green after updating onto current main.

[cv]

Reviewed exact head ce1f066 after its current-main refresh. The SSH hint no longer infers a copy-pastable destination from SSH_CONNECTION; it uses , preserves explicit destinations, and covers aliases, NAT, ProxyJump, quiet/non-quiet output, and deterministic env injection. All 32 checks are green, DCO and all 4 commits are Verified, CodeRabbit is clear, and no current advisor blocker exists.

[cv]

Renewing approval on exact head 4f00992 after the docs-only current-main refresh. The reviewed SSH-destination fix is unchanged; all 30 checks are green, merge state is clean, all 5 commits are Verified, and the exact-head gate passes.