refactor(onboard): extract sandbox launch envelope by cv · Pull Request #5140 · NVIDIA/NemoClaw

cv · 2026-06-10T13:46:27Z

Summary

Extracts the createSandbox runtime launch envelope into a focused helper. This keeps sandbox runtime env assembly, dashboard/runtime proxy propagation, host credential stripping, and openshell sandbox create -- env ... nemoclaw-start command construction in one testable module while preserving the existing create flow.

Related Issue

Refs #3802

Changes

Added prepareSandboxCreateLaunch in src/lib/onboard/sandbox-create-launch.ts.
Replaced inline runtime env, subprocess env, startup command, and create command assembly in createSandbox with the new helper.
Added focused coverage for OpenClaw runtime env propagation, Hermes dashboard env propagation, proxy/minimal-bootstrap/extra-placeholder forwarding, invalid runtime proxy filtering, stripping KUBECONFIG / SSH_AUTH_SOCK from the sandbox subprocess env, and preserving argv boundaries through the production shell renderer.

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

Targeted local checks run:

npx @biomejs/biome format --write src/lib/onboard/sandbox-create-launch.test.ts
npx @biomejs/biome lint src/lib/onboard.ts src/lib/onboard/sandbox-create-launch.ts src/lib/onboard/sandbox-create-launch.test.ts
npm run build:cli
npx vitest run src/lib/onboard/sandbox-create-launch.test.ts src/lib/onboard/openclaw-runtime-env.test.ts src/lib/onboard/host-proxy-env.test.ts src/lib/onboard/extra-placeholder-keys.test.ts test/onboard.test.ts
npm run typecheck:cli
git diff --check

GitHub validation on head d2c9122c67bcdd9790cb5fbd05f27e874ee2afd8:

PR checks: green on refactor(onboard): extract sandbox launch envelope #5140 after follow-up commit d2c9122c6.
PR Review Advisor: 0 needs attention, 0 worth checking, 0 nice ideas after adding production shell-boundary coverage.
CodeRabbit: skipped while draft.
Recommended live E2Es passed in https://github.com/NVIDIA/NemoClaw/actions/runs/27281412301: cloud-onboard-e2e, messaging-providers-e2e, telegram-injection-e2e, plus optional hermes-dashboard-e2e.
Recommended live scenario passed in https://github.com/NVIDIA/NemoClaw/actions/runs/27281412073: ubuntu-repo-cloud-openclaw.

Local broad-hook note:

Full npx prek run --all-files remains blocked locally by the unrelated test/release-latest-tag.test.ts fixture commit signing failure (/home/cvillela/.ssh/git-signing-key.pub missing private key). This PR does not touch that release test file.
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
npm run 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: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

Refactor
- Reorganized sandbox creation and environment configuration logic into a dedicated module.
Tests
- Added comprehensive test coverage for sandbox launch command generation, environment variable propagation, proxy validation, and command injection prevention.

copy-pr-bot · 2026-06-10T13:46:31Z

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 · 2026-06-10T13:46:35Z

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: dca96c51-8dc0-4e9e-acc4-a88049f35c6e

📥 Commits

Reviewing files that changed from the base of the PR and between cf1e701 and 63315c8.

📒 Files selected for processing (3)

src/lib/onboard.ts
src/lib/onboard/sandbox-create-launch.test.ts
src/lib/onboard/sandbox-create-launch.ts

📝 Walkthrough

Walkthrough

This PR extracts sandbox creation command and environment construction from onboard.ts into a new sandbox-create-launch module. The refactoring consolidates dashboard port forwarding, environment variable building (OpenClaw, Hermes, proxy), credential filtering, and command assembly into reusable contracts and a testable function.

Changes

Sandbox launch extraction and refactor

Layer / File(s)	Summary
Sandbox launch contracts and implementation `src/lib/onboard/sandbox-create-launch.ts`	Introduces `SandboxCreateLaunchInput` and `SandboxCreateLaunch` interfaces defining the function contract. `prepareSandboxCreateLaunch()` computes effective dashboard port, builds environment argument lists with validated proxy forwarding (`NEMOCLAW_PROXY_HOST`/`NEMOCLAW_PROXY_PORT`), removes `KUBECONFIG` and `SSH_AUTH_SOCK`, and constructs the final sandbox startup and create commands.
Sandbox launch test verification `src/lib/onboard/sandbox-create-launch.test.ts`	Vitest suite validates command/env construction for OpenClaw agents (proxy, dashboard port, env args, startup command), Hermes agents (dashboard vars, excluding OpenClaw env), invalid proxy overrides, and argv boundary preservation via shell execution (ensuring injected values in Dockerfile/URL/proxy do not execute).
Onboard.ts integration `src/lib/onboard.ts`	Imports `sandboxCreateLaunch` module; removes `isValidProxyHost`, `isValidProxyPort`, and `buildSubprocessEnv` imports; replaces 37 lines of inlined sandbox env/command construction with a call to `prepareSandboxCreateLaunch()` in the `createSandbox` path, reducing complexity while preserving sandbox create/ready-wait flow.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

NVIDIA/NemoClaw#5128: Centralizes dashboard port and URL resolution in createSandbox to enable effective port propagation into sandbox launch commands.
NVIDIA/NemoClaw#5130: Refactors dashboard port and CHAT_UI_URL forwarding in the sandbox setup flow, sharing integration points with this extraction.

Suggested reviewers

prekshivyas

Poem

🐰 ✨ From tangled onboard lines so long,
A rabbit hops with focused song—
Extract, contract, test with care,
Sandbox launch is now more fair!
Clean and bold, the refactor's strong! 🚀

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% 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 'refactor(onboard): extract sandbox launch envelope' directly and clearly describes the main change—extracting sandbox launch logic into a new helper module—which is the central purpose of this PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/onboard-sandbox-launch-flow

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

github-actions · 2026-06-10T13:49:05Z

E2E Advisor Recommendation

Required E2E: cloud-onboard-e2e, credential-sanitization-e2e
Optional E2E: telegram-injection-e2e, runtime-overrides-e2e

Dispatch hint: cloud-onboard-e2e,credential-sanitization-e2e

Auto-dispatched E2E: cloud-onboard-e2e, credential-sanitization-e2e via nightly-e2e.yaml at 63315c87fe07d03c789fc009d82157489f554c53 — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

cloud-onboard-e2e (medium): Exercises the real install/onboard path through live sandbox creation and health checks, directly covering the refactored sandbox launch command used by createSandbox().
credential-sanitization-e2e (medium): Validates the sandbox credential boundary on a real onboarded sandbox; this is required because the changed helper owns the allowlisted subprocess env and explicitly strips host infrastructure secrets before sandbox create.

Optional E2E

telegram-injection-e2e (medium): Useful extra confidence for shell/argv injection defenses because this PR changes the shell-rendered openshell sandbox create command boundary, although the newly added unit test already targets argv preservation.
runtime-overrides-e2e (medium): Adjacent confidence for runtime environment handling and sandbox entrypoint config patching, but it does not directly exercise openshell sandbox create launch arguments.

New E2E recommendations

sandbox launch env envelope (medium): Existing E2E coverage exercises onboarding and credential sanitization broadly, but there does not appear to be a focused live test that sets custom CHAT_UI_URL, NEMOCLAW_PROXY_HOST, NEMOCLAW_PROXY_PORT, and host-only env such as KUBECONFIG/SSH_AUTH_SOCK, then asserts the launched sandbox received only the intended runtime variables.
- Suggested test: Add a live sandbox-create launch env E2E that onboards with custom dashboard/proxy overrides and verifies inside the sandbox that dashboard/proxy envs and placeholder keys are present while host infrastructure secrets are absent.

Dispatch hint

Workflow: .github/workflows/nightly-e2e.yaml
jobs input: cloud-onboard-e2e,credential-sanitization-e2e

github-actions · 2026-06-10T13:49:07Z

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: ubuntu-repo-cloud-openclaw
Optional Vitest E2E scenarios: ubuntu-repo-docker-post-reboot-recovery

Dispatch required Vitest E2E scenarios:

gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required Vitest E2E scenarios

ubuntu-repo-cloud-openclaw: The PR refactors the core onboarding sandbox-create launch path used by Ubuntu Docker cloud OpenClaw onboarding, including runtime env forwarding, dashboard port propagation, proxy env handling, placeholder key forwarding, sandbox subprocess env sanitization, and the rendered openshell sandbox create -- env ... nemoclaw-start command. This live-supported scenario is the smallest trusted typed Vitest scenario that exercises that sandbox creation surface end-to-end.
- Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Optional Vitest E2E scenarios

ubuntu-repo-docker-post-reboot-recovery: Adjacent live-supported Ubuntu Docker OpenClaw scenario that also traverses sandbox creation before validating host-side registry/container preservation after a simulated post-reboot recovery lifecycle. Useful if extra confidence is desired for sandbox create side effects, but the primary launch-path coverage is provided by ubuntu-repo-cloud-openclaw.
- Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-docker-post-reboot-recovery

Relevant changed files

src/lib/onboard.ts
src/lib/onboard/sandbox-create-launch.ts

github-actions · 2026-06-10T13:50:10Z

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 0 nice ideas
Since last review: 0 prior items resolved, 0 still apply, 0 new items found

Consider writing more tests for

**Runtime validation** — createSandbox wires prepareSandboxCreateLaunch output into streamSandboxCreate and Docker GPU patch without changing the startup argv seen by OpenShell.. Unit coverage is strong for the extracted helper, including security-sensitive shell rendering, but the changed surface is host/sandbox infrastructure glue whose final behavior depends on OpenShell sandbox creation, sandbox startup, and Docker GPU patch handoff.
**Runtime validation** — sandbox create with custom CHAT_UI_URL dashboard port and NEMOCLAW_PROXY_HOST/NEMOCLAW_PROXY_PORT starts the sandbox on the expected dashboard port with the proxy override visible to startup.. Unit coverage is strong for the extracted helper, including security-sensitive shell rendering, but the changed surface is host/sandbox infrastructure glue whose final behavior depends on OpenShell sandbox creation, sandbox startup, and Docker GPU patch handoff.
**Runtime validation** — sandbox startup cannot see host KUBECONFIG or SSH_AUTH_SOCK while allowed non-secret subprocess env remains available.. Unit coverage is strong for the extracted helper, including security-sensitive shell rendering, but the changed surface is host/sandbox infrastructure glue whose final behavior depends on OpenShell sandbox creation, sandbox startup, and Docker GPU patch handoff.
**Runtime validation** — extraPlaceholderKeys forwards only placeholder key names into the runtime env and never credential values.. Unit coverage is strong for the extracted helper, including security-sensitive shell rendering, but the changed surface is host/sandbox infrastructure glue whose final behavior depends on OpenShell sandbox creation, sandbox startup, and Docker GPU patch handoff.
**Acceptance clause:** Refs Umbrella: refactor onboarding into a serializable FSM #3802 — add test evidence or identify existing coverage. The PR body references Umbrella: refactor onboarding into a serializable FSM #3802, but trusted deterministic linked-issue context did not include issue Umbrella: refactor onboarding into a serializable FSM #3802 body/comments or literal acceptance clauses; deterministic linkedIssues is empty. The observable refactor scope is covered by the diff and tests.

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

github-actions · 2026-06-10T14:11:39Z

Selective E2E Results — ✅ All requested jobs passed

Run: 27281412301
Target ref: codex/onboard-sandbox-launch-flow
Workflow ref: main
Requested jobs: cloud-onboard-e2e,messaging-providers-e2e,telegram-injection-e2e,hermes-dashboard-e2e
Summary: 4 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success
hermes-dashboard-e2e	✅ success
messaging-providers-e2e	✅ success
telegram-injection-e2e	✅ success

wscurran · 2026-06-10T14:53:21Z

✨
Related open PRs:

#5140 refactor(onboard): extract sandbox launch envelope

Related open issues:

#3802 Umbrella: refactor onboarding into a serializable FSM

…ort-merge

…shboard-merge

# Conflicts: # src/lib/onboard.ts

github-actions · 2026-06-11T09:46:11Z

Selective E2E Results — ✅ All requested jobs passed

Run: 27337978811
Target ref: 63315c87fe07d03c789fc009d82157489f554c53
Workflow ref: main
Requested jobs: cloud-onboard-e2e,credential-sanitization-e2e
Summary: 2 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success
credential-sanitization-e2e	✅ success

cv added 13 commits June 10, 2026 01:31

refactor(onboard): extract docker gateway runtime helpers

d2689c5

test(onboard): cover docker gateway runtime helpers

cfae232

docs(onboard): explain docker gateway runtime boundary

75f5a52

refactor(onboard): extract dashboard port create resolver

128ef56

test(onboard): document malformed dashboard URL resolution

8d9f4c1

refactor(onboard): centralize reused dashboard metadata

b6ea38f

test(onboard): cover disabled Hermes dashboard reuse metadata

2d9d81a

refactor(onboard): extract sandbox registration payload

318a002

refactor(onboard): extract messaging preparation

106d27d

test(onboard): cover messaging preparation edge cases

45b449b

refactor(onboard): extract build context staging

97b99bc

test(onboard): cover build context staging edge cases

a928abd

refactor(onboard): extract sandbox launch envelope

1521702

cv self-assigned this Jun 10, 2026

cv mentioned this pull request Jun 10, 2026

Umbrella: refactor onboarding into a serializable FSM #3802

Open

test(onboard): cover sandbox launch shell boundaries

d2c9122

wscurran added area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow area: sandbox OpenShell sandbox lifecycle, runtime, config, or recovery refactor PR restructures code without intended behavior change labels Jun 10, 2026

cv added the v0.0.64 Release target label Jun 10, 2026

cv added 3 commits June 10, 2026 23:48

Merge remote-tracking branch 'origin/main' into codex/tmp-dashboard-p…

f959ccc

…ort-merge

Merge branch 'codex/tmp-dashboard-port-merge' into codex/tmp-reuse-da…

c06aae6

…shboard-merge

Merge branch 'codex/tmp-reuse-dashboard-merge' into HEAD

c66b889

# Conflicts: # src/lib/onboard.ts

cv added 3 commits June 10, 2026 23:57

Merge branch 'codex/tmp-registration-merge' into HEAD

c35baff

# Conflicts: # src/lib/onboard.ts

Merge branch 'codex/tmp-messaging-prep-merge' into HEAD

9e0ded0

Merge branch 'codex/tmp-build-context-merge' into HEAD

a59867f

Base automatically changed from codex/onboard-build-context-flow to main June 11, 2026 09:31

Merge remote-tracking branch 'origin/main' into codex/pr-5140-update

63315c8

# Conflicts: # src/lib/onboard.ts

cv marked this pull request as ready for review June 11, 2026 09:37

Conversation

cv commented Jun 10, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Type of Change

Verification

Summary by CodeRabbit

Uh oh!

copy-pr-bot Bot commented Jun 10, 2026

Uh oh!

coderabbitai Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Advisor Recommendation

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Dispatch hint

Uh oh!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vitest E2E Scenario Recommendation

Vitest E2E Scenario Advisor

Required Vitest E2E scenarios

Optional Vitest E2E scenarios

Relevant changed files

Uh oh!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor

Uh oh!

github-actions Bot commented Jun 10, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

wscurran commented Jun 10, 2026

Uh oh!

github-actions Bot commented Jun 11, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cv commented Jun 10, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 10, 2026 •

edited

Loading