docs(sandboxes): add IPv6 loopback example to Port Forwarding

[andrewwhitecdw]

Summary

Adds the missing IPv6 loopback example to the Port Forwarding documentation. The core behavior this example demonstrates already landed on main via #2552 (bracketed SSH bind argument and access URL, closing #2279); after #3705 moved the page, the current Port Forwarding section at docs/how-it-works/sandboxes/overview.mdx only shows the IPv4 form. This PR supplies the IPv6 example there — documentation only, no code changes.

openshell forward start ::1:8000 my-sandbox
# Local URL: http://[::1]:8000/

Related Issue

Fixes #4504

Changes

• Add an IPv6 loopback example (positional [bind_address:]port form, bracketed access URL) to the Port Forwarding section of docs/how-it-works/sandboxes/overview.mdx

Testing

• Docs-only change; example verified against current CLI parsing and the formatters landed in fix(cli): bracket IPv6 bind literals in SSH forwards #2552
• E2E tests added/updated (if applicable)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[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.

[github-actions]

All contributors have signed the DCO ✍️ ✅
_{Posted by the DCO Assistant Lite bot.}

[andrewwhitecdw]

I have read the DCO document and I hereby sign the DCO.

[johntmyers]

gator-agent

PR Review Status

Validation: This is a project-valid, concentrated core bug fix. It restores valid OpenSSH and URL formatting for an IPv6 bind address; PR #2409 was the same author's earlier submission and was closed only by the vouch gate.
Head SHA: bc87935b91607195c7c6b5e281a78e8b55b7cbc8

Review findings:

• The focused implementation and regression tests are sound; no correctness or security defect was found.
• The new helper leaves identical IPv6-bracketing logic in format_gateway_url(); the inline suggestion asks to consolidate that logic so the two paths cannot drift.
• This changes direct user-visible forwarding behavior and printed access URLs. Please add an IPv6 example to the existing Port Forwarding section in docs/sandboxes/manage-sandboxes.mdx, including the bracketed http://[::1]:8000/ output. Existing navigation already covers that page, so docs/index.yml does not need to change.

Docs: missing for this direct UX change.

E2E/pipeline: deferred until review feedback is resolved.

Next state: gator:in-review

[johntmyers]

gator-agent

PR Review Status

Validation: This remains a project-valid, concentrated core bug fix for invalid IPv6 formatting in OpenSSH forward arguments and printed access URLs.
Head SHA: e28f49ccdda1e6cec0ce9dd0c1fd51d2537262c9

Thanks @andrewwhitecdw. I checked the latest commit against both prior requests: consolidating IPv6 bracketing through bracket_ipv6() is resolved, and the requested Fern page now includes an IPv6 example. The code and focused regression coverage are sound, with no correctness or security defect found.

Review findings:

• The new documentation command uses a flag that openshell forward start does not support; the inline warning gives the valid positional syntax.

Docs: the existing page and navigation location are correct, but the example command must be fixed.

E2E/pipeline: deferred until this review finding is resolved.

Next state: gator:in-review

[andrewwhitecdw]

Fixed — the example now uses the positional [bind_address:]port form (openshell forward start ::1:8000 my-sandbox) and the prose no longer mentions -b/--bind-addr.

[johntmyers]

gator-agent

Blocked

Head SHA: 8581114

Thanks @andrewwhitecdw. I checked your update: the IPv6 documentation example now uses the valid positional [bind_address:]port form, and the earlier documentation review finding is resolved.

Gator is blocked because this PR currently has merge conflicts with main.

Next action: rebase or merge main into the PR branch, resolve the conflicts, and push the updated head. Gator will re-review the new head before starting the pipeline.

[johntmyers]

gator-agent

PR Review Status

Validation: This remains a project-valid, concentrated IPv6 forwarding documentation fix. The equivalent core behavior is now present on main, so the rebased effective patch is the focused user-facing example.
Head SHA: f684685195de861ed1d48544ada4acd5fbb54e2c
Base SHA: 28f3bee0ce7e89c845016fc0554f8990a31543bb
Merge base SHA: 28f3bee0ce7e89c845016fc0554f8990a31543bb
Patch ID: 77adeb1e5b3f916f9ddaa3c25e6871176469df6f
Gator payload: 2
Review mode: follow_up
Previous reviewed SHA: e28f49ccdda1e6cec0ce9dd0c1fd51d2537262c9

Thanks @andrewwhitecdw. I checked the rebased head and your corrected positional [bind_address:]port example. The prior documentation warning remains resolved, and the old merge-conflict blocker is cleared.

Blocking findings:

• No blocking findings remain.

Carried findings:

• None; the prior consolidation and documentation obligations remain resolved.

Docs: the existing Fern page now shows the valid IPv6 command and bracketed access URL; existing navigation already covers it.

E2E: no test:e2e label is needed for the current docs-only effective patch. Branch Checks and Helm Lint still require the current-head copy-pr mirror.

Next state: gator:watch-pipeline

[johntmyers]

/ok to test f684685

[github-actions]

This pull request has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity.

[andrewwhitecdw]

Thanks @johntmyers — this PR is up to date on review feedback:

• The format_gateway_url() duplication you flagged is resolved: on this branch it calls the shared bracket_ipv6() helper, so URL and forwarding behavior can no longer drift.
• The Port Forwarding docs example uses the correct positional [bind_address:]port form (openshell forward start ::1:8000 my-sandbox — no -b/--bind-addr).

Apologies for the churn from the accidental close earlier. No pending review items remain on my side — happy to address anything else, and please let me know if you'd rather I rebase onto current main before further review.

[github-actions]

This pull request has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity.

[andrewwhitecdw]

Bumping this to keep it from going stale — still actively engaged and the branch remains ready for review. All prior review feedback is addressed in the current head (shared bracket_ipv6() helper for URL and forwarding paths); nothing is waiting on my side. Happy to make further changes if anything new comes up.

[github-actions]

This pull request has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity.

[johntmyers]

gator-agent

Relevance Assessment

Partially applicable: the original code fix has landed; the IPv6 documentation example remains useful and missing from current main. I compared freshly fetched main fe316067dc2503062235106b886c206e9d8ca079 with PR head 5878faf546e571f0e02ec402e88e31252bb88e12. This conclusion comes from the implementation, tests, and remaining diff, rather than the PR's age or conflicts.

Thanks @andrewwhitecdw. I checked your September updates about the shared helper, corrected positional command, and resolved review feedback. Both earlier Gator threads remain resolved; the current effective patch matches the last reviewed patch, so those obligations stay resolved without another review of unchanged code.

• Original forwarding problem is fixed on main. PR #2552, landed as 0cecb54249a8bbdf5a9d84140acf52d823011dab, addressed the same unbracketed SSH argument and invalid access URL (and closed the related issue bug: support IPv6 bind addresses for SSH forwarding #2279). Current forward.rs:664–719 parses ::1:8080, brackets the SSH bind through bracket_ipv6_host(), and builds the access URL through format_gateway_url(). The shared helper remains at lines 892–906. The live CLI SSH builder consumes that formatter, and lines 968–974 print spec.access_url().
• Main retains concrete regression coverage. forward_spec_ssh_forward_arg_brackets_ipv6_literal asserts [::1]:8080:127.0.0.1:8080 and the IPv6 wildcard case; forward_spec_access_url_ipv6 asserts http://[::1]:8080/ and wildcard-to-localhost behavior. I inspected these assertions; Rust/Cargo are unavailable here, so I did not execute the unit suite. A local, connection-free ssh -G -F /dev/null check accepted the bracketed argument and rejected the original unbracketed argument.
• The remaining scope is documentation only. The current PR addition is seven lines showing openshell forward start ::1:8000 my-sandbox and the bracketed URL; it contains no remaining core implementation or test changes. PR #3705, commit 92448680567722b14c9315e72c6f8e0971785ffc, moved that page to docs/how-it-works/sandboxes/overview.mdx. Its Port Forwarding section still lacks this IPv6 example. Current CLI parsing still accepts the positional syntax, and existing navigation already points to the new page.

Action required: @andrewwhitecdw, rebase onto current main, resolve the conflicts by carrying only the IPv6 example into the current Port Forwarding section, and preserve the newer documentation around it. Retitle the PR to reflect its remaining documentation scope; no replacement core fix is needed. Gator will reconcile the updated patch and required current-head checks afterward. Runtime E2E is unnecessary for the existing docs-only patch; pipeline handoff remains deferred while merge conflicts persist.

Gator metadata

• Head SHA: 5878faf546e571f0e02ec402e88e31252bb88e12
• Current main SHA: fe316067dc2503062235106b886c206e9d8ca079
• API base SHA: 877ddbacb4b915fa1d5bc6f02302d9a5c13a18e1
• Merge base SHA: 28f3bee0ce7e89c845016fc0554f8990a31543bb
• Patch ID: 77adeb1e5b3f916f9ddaa3c25e6871176469df6f
• Gator payload: 12
• Review mode: already_reviewed (equivalent effective patch)
• Previous reviewed SHA: f684685195de861ed1d48544ada4acd5fbb54e2c
• Next state: gator:blocked
• Blocked reason: merge_conflicts

[andrewwhitecdw]

Done — rebased onto current main and retitled.

• Resolved the conflict by dropping the old docs/sandboxes/manage-sandboxes.mdx change and carrying only the IPv6 example into the current Port Forwarding section of docs/how-it-works/sandboxes/overview.mdx, after the "OpenShell prints the local URL…" paragraph and before the newer multiplexing/foreground sentences from docs: refresh architecture and agent guides #3705.
• Remaining diff is 8 added lines, docs only — no core changes, since fix(cli): bracket IPv6 bind literals in SSH forwards #2552 landed the fix.
• Commit rewritten as docs(sandboxes): add IPv6 loopback example to Port Forwarding (new head ea93e413), PR retitled to match.

Gator should be able to reconcile the updated patch now.

[johntmyers]

/ok to test ea93e41

[johntmyers]

gator-agent

PR Review Status

Thanks @andrewwhitecdw. I checked your rebase and retitle: the remaining eight added lines place the valid positional IPv6 command and bracketed URL in the current Port Forwarding section, preserving the newer multiplexing and foreground text. Merge conflicts are cleared. The independent follow-up review found no blocking defects; both earlier Gator findings remain resolved.

The existing relevance assessment still holds against freshly fetched main 82977e27a438c8a6a1072498432f9f7c75a33a85: #2552 already fixed the core behavior, while this PR supplies the missing example after #3705 moved the page. Main's forward formatters and SSH regression test retain IPv6 brackets; the access-URL test covers loopback and wildcard display. A connection-free OpenSSH check accepted the bracketed argument and rejected the original unbracketed argument. Cargo is unavailable here, so I did not execute Rust tests.

Action required: @andrewwhitecdw and a maintainer, link an issue covering this remaining documentation work with state:accepted using Fixes #NNN or Closes #NNN, then rerun PR Issue Acceptance. Its current-head failure explicitly requires that linkage. The PR description also still describes the superseded core patch; please align it with the docs-only scope.

I posted /ok to test for the full current head and confirmed Branch Checks and Helm Lint are queued. Runtime E2E is unnecessary for this docs-only change. Gator remains blocked on issue acceptance while checks run.

Gator metadata

• Head SHA: ea93e4136369535b1882f0f0f97384958452d93e
• Base SHA: 82977e27a438c8a6a1072498432f9f7c75a33a85
• Merge base SHA: 82977e27a438c8a6a1072498432f9f7c75a33a85
• Patch ID: 4561e0fd1d32d182f8d443e72cb4eea267302674
• Gator payload: 12
• Review mode: follow_up
• Previous reviewed SHA: f684685195de861ed1d48544ada4acd5fbb54e2c
• Blocking findings: none
• Carried findings: none; prior resolved dispositions preserved
• Docs: current Fern page updated; existing navigation remains valid
• E2E: not required for docs-only effective patch
• Checks: DCO passed; Branch Checks and Helm Lint queued; PR Issue Acceptance failed; Trivy Changes awaiting workflow authorization
• Review budget exhausted: no
• Maintainer decision required: no review convergence decision; issue acceptance required
• Next state: gator:blocked
• Blocked reason: issue_acceptance_required

[andrewwhitecdw]

Issue linkage done:

• Created docs: add IPv6 loopback example to Port Forwarding docs #4504 (docs: add IPv6 loopback example to Port Forwarding docs) covering exactly the remaining scope — the core fix landed via fix(cli): bracket IPv6 bind literals in SSH forwards #2552, and the example went missing from the current page after docs: refresh architecture and agent guides #3705's move.
• PR body rewritten to the docs-only scope and now links Fixes #4504.

@johntmyers — over to you for the state:accepted label on #4504 so PR Issue Acceptance can pass. DCO is green; Branch Checks and Helm Lint were queued on the current head.

[johntmyers]

gator-agent

Monitoring Complete

Monitoring is complete because PR #2449 merged at 2026-10-14 00:08:53 UTC. The IPv6 loopback documentation example landed in docs/how-it-works/sandboxes/overview.mdx; the earlier relevance assessment and resolved review findings remain preserved. Linked issue #4504 was accepted by @johntmyers and is now closed.

Thanks @andrewwhitecdw. I confirmed your docs-only rebase, revised description, and Fixes #4504 linkage. Maintainer approval, Branch Checks, Helm Lint, and Trivy Changes passed. The earlier issue-acceptance run failed before the issue was accepted; no further test dispatch or gate reconciliation is needed for this merged PR.

I removed the active gator:* label because there is nothing left for Gator to monitor on this PR.

Gator metadata

• Head SHA: ea93e4136369535b1882f0f0f97384958452d93e
• Merge commit: 58fdb40246e9e11e52533bc358d6c553b9f79754
• Gator payload: 12
• Terminal state: merged