[xuanchangfeng]

ELI5

An operator running orca serve behind an SSH port-forward or tunnel can keep the listener on loopback with --bind 127.0.0.1. Leaving out the flag preserves the existing behavior.

What Changed

• Add optional --bind <addr> to the CLI and direct Electron serve parser. Accept literal IP addresses, with localhost mapped to 127.0.0.1.
• Reuse one address resolver in shared/runtime-bind-address.ts; keep orcad's existing exports for its current callers. CLI flag parsing follows the existing port-flag pattern.
• Validate before starting any child, including runtime selection. Use upstream's shared orcad-serve-argv.ts to forward the pin to both Electron and orcad.
• Preserve both hosts' defaults when the flag is absent. An explicit pin replaces the orcad adapter's all-interfaces default.
• Reject a non-wildcard pin with --mobile-pairing, whose listener widening would fail. Keep --pairing-address independent for SSH-forward and tunnel endpoints.
• Update CLI help and examples.

Why

The runtime already implements pinnedBindHost and refuses to widen a pinned listener. This exposes that mechanism through orca serve, without adding a separate binding policy or changing defaults.

Linked Issue

Fixes #25837

Visual Proof

N/A: CLI arguments and startup behavior only.

Testing

Updated against main@885cd6ff4 in 52d1f17cc on 2026-10-22. Resolved one import conflict by retaining both bind validation and upstream speech recognizer discovery; no new feature behavior was added in this synchronization.

• Local @orca/process-host package build: passed.
• 11 focused suites with one worker: 155 passed / 4 macOS-only skipped. Coverage includes both runtime launch paths, defaults, localhost normalization, IPv6, invalid inputs rejected before runtime selection, CLI/Electron flag parity, mobile-pairing conflicts existing listener-pin enforcement, and upstream speech-recognizer resource discovery.
• CLI typecheck: node config/scripts/run-typecheck-projects-in-parallel.mjs --compiler=native --project=config/tsconfig.tc.cli.json, passed.
• All 15 changed TypeScript files: oxlint --threads=2, React Doctor lint, and oxfmt --check, passed.
• git diff origin/main --check: passed.
• Separately checked the existing process-host wrapper on real Windows Node 24.14.0 with the upstream argument corpus and serve-shaped arguments: 28 checks passed, including literal shell metacharacters. No process-host production changes were needed.

No dependencies were downloaded or installed for the 2026-10-22 update. Local tools were previously restored offline from the previously verified main@98b4139e0 dependency snapshot, with install scripts disabled. The TypeScript, Vitest, oxlint and oxfmt version requirements are unchanged. The latest upstream manifests and lockfile are unchanged in this PR. CI must still validate the current lockfile and upstream's default Bun typecheck path.

• Real end-to-end orca serve --bind launch tested
• Automated tests added/updated

AI Disclosure

Original implementation assisted by the pi coding agent (DeepSeek V4.1 Flash), with planning and review assistance from Claude. Upstream synchronization, conflict resolution, shared validation cleanup and local verification were assisted by OpenAI Codex. The author owns the submission.

Review

The update follows upstream's runtime selection, shared argv construction, service supervision, profile pinning and process-host spawning. Existing orcad address-resolution exports remain compatible. There is no protocol or persisted-data change.

Agent skill upstream boundary

• Not applicable; no upstream skill-installer source or other skill package material is copied.

Notes

Full tests, full lint, desktop/mobile builds and a real server smoke test were not run locally. A previous full run exhausted the VM, so validation ran sequentially with one test worker and reduced memory/thread budgets.

The merge commit skipped the default staged-file hook because it would process the upstream merge's unrelated files. The corresponding lint/format checks were run on this PR's actual diff instead. No hook configuration was changed.

Checklist

• Focused optional listener-pin behavior
• Before/after behavior and rationale described
• Cross-platform and SSH/tunnel behavior considered
• Relevant tests, CLI typecheck and changed-file lint/format pass
• Full CI passes

Author

X (Twitter) handle: N/A

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: ba73cd31-62c6-4169-ab19-db5ca56d5390

📥 Commits

Reviewing files that changed from the base of the PR and between f652174 and 69948b4.

📒 Files selected for processing (5)

• config/tsconfig.cli.json
• src/cli/handlers/core.ts
• src/cli/index-serve-command.test.ts
• src/cli/runtime/launch.test.ts
• src/cli/runtime/launch.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• src/cli/runtime/launch.test.ts
• src/cli/index-serve-command.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📝 Walkthrough

The serve command now accepts an optional --bind <addr> value. The option accepts literal IP addresses and maps localhost to 127.0.0.1. A non-wildcard bind is rejected with mobile pairing, while a loopback bind can be used with a tunnel pairing address. When the option is supplied, startup forwards the resolved host as pinnedBindHost. The default behavior remains unchanged when the option is absent.

Priority: ⬇️ Low

Severity of issue fixed: Low

Merge Risk: ⚪ Minimal · up to 69948

The new bind option is forwarded to runtime startup, while invalid values are rejected before the child starts. No actionable merge-blocking risk remains.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 10 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		[#25837] The existing PR changes add the requested --bind option, preserve the default when it is absent, validate literal IP addresses with localhost mapped to 127.0.0.1, forward the bind pin t…
Out of Scope Changes check		All changes support [#25837]. The CLI validation, child argument forwarding, TypeScript project inclusion, tests, help, and documentation implement or verify the requested serve bind option. No unrela…
Title check		The title clearly and concisely describes the primary change: adding an optional --bind address to pin the runtime listener.
Description check		The description covers the required sections, explains the user-facing change and rationale, links issue #25837, documents testing and limitations, and addresses compatibility and security considerati…

Full details: Linked Issues check

Explanation

[#25837] The existing PR changes add the requested --bind option, preserve the default when it is absent, validate literal IP addresses with localhost mapped to 127.0.0.1, forward the bind pin to the runtime, and reject non-wildcard binds with --mobile-pairing. The current changes also validate the CLI value before spawning a child, including on Windows shell launch paths. Tests cover forwarding, omitted values, aliases, hostnames, shell metacharacters, and rejection before launch. Help and documentation cover the option and its constraints.

Full details: Out of Scope Changes check

Explanation

All changes support [#25837]. The CLI validation, child argument forwarding, TypeScript project inclusion, tests, help, and documentation implement or verify the requested serve bind option. No unrelated change is evident.

Full details: Description check

Explanation

The description covers the required sections, explains the user-facing change and rationale, links issue #25837, documents testing and limitations, and addresses compatibility and security considerations.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 10 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: ccd82c39-95ac-4444-9ec8-ff7cd8b80766

📥 Commits

Reviewing files that changed from the base of the PR and between b752131 and 7c28c50.

📒 Files selected for processing (7)

• docs/reference/headless-linux-server.md
• src/cli/specs/serve.ts
• src/main/startup/main-process-runtime-launch.ts
• src/main/startup/serve-mode-argv.ts
• src/main/startup/serve-options.test.ts
• src/main/startup/serve-options.ts
• src/shared/serve-option-validation.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: c1bac909-9d74-4efe-9fa6-58f392284696

📥 Commits

Reviewing files that changed from the base of the PR and between 7c28c50 and f652174.

📒 Files selected for processing (4)

• src/cli/handlers/core.ts
• src/cli/index-serve-command.test.ts
• src/cli/runtime/launch.test.ts
• src/cli/runtime/launch.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

[xuanchangfeng]

Hi @nwparker, I saw your recent work on orca serve in #30120 and wondered if you could help review this PR or point me to the right person.

This is my first contribution to Orca, opened on October 6. It adds an optional --bind flag so users can pin the listener to a specific address, for example loopback when accessing it through a tunnel. When you have a chance, could you let me know whether this feature is something the team would consider? If a different approach would fit better, or this is outside the project's plans, that guidance would also be very helpful.

I've updated the PR against main@98b4139e0 in 6e4b56c49, resolving all five merge conflicts and carrying the bind option through both Electron serve and the selected orcad host. Omitting the flag preserves the existing defaults.

Local validation: 10 focused suites, 151 passed / 4 skipped; CLI typecheck, changed-file lint (including the React Doctor config), formatting and whitespace checks passed. The full suite/build were not run locally; the PR description records the resource limits and checks run. The seven CI workflow runs are awaiting maintainer approval; could someone with permission approve them when convenient?

I appreciate that review time is limited. Thank you for your time, and I'm happy to make further changes.