fix(ide): surface explicit gVisor sandbox network isolation error

[elberthc-byte]

Summary

Surfaces a clear, actionable diagnostic message when IDE companion connection fails inside a gVisor (runsc) sandbox where network isolation blocks host loopback communication—instead of misleadingly instructing the user to run /ide install—and documents this limitation in the sandboxing and IDE integration guides.

Details

1. Forward Sandbox & Stdio Environment Variables (packages/cli/src/utils/sandbox.ts):

   • Forward GEMINI_CLI_IDE_SERVER_STDIO_COMMAND and GEMINI_CLI_IDE_SERVER_STDIO_ARGS into both Docker/Podman/gVisor (start_sandbox) and LXC (start_lxc_sandbox) containers alongside GEMINI_CLI_IDE_SERVER_PORT and GEMINI_CLI_IDE_WORKSPACE_PATH (while keeping GEMINI_CLI_IDE_AUTH_TOKEN unexposed inside the untrusted sandbox environment).
   • Forward GEMINI_SANDBOX into the container (ensuring GEMINI_SANDBOX=runsc is set whenever config.command === 'runsc').

2. Allow Container Host Headers in Companion Server (packages/vscode-ide-companion/src/ide-server.ts):

   • Add host.docker.internal:${this.port} and host.containers.internal:${this.port} (matched case-insensitively) to allowedHosts in IDEServer, matching the host resolution performed by getIdeServerHost() inside containers.

3. Centralized gVisor (runsc) Detection & Diagnostic (packages/core/src/ide/ide-connection-utils.ts, packages/core/src/ide/ide-client.ts):

   • Add centralized isGvisorSandbox() helper in ide-connection-utils.ts inspecting SANDBOX and GEMINI_SANDBOX.
   • Surface an explicit gVisor network isolation diagnostic message in IdeClient.connect() both when workspacePath is undefined (e.g., when the host's /tmp/gemini/ide discovery directory is unmounted inside the runsc container and GEMINI_CLI_IDE_WORKSPACE_PATH is unset) and when HTTP/stdio connection attempts fail under runsc, while preserving specific workspace validation messages (Directory mismatch. and please open a workspace folder).

4. Documentation (docs/cli/sandbox.md, docs/ide-integration/index.md):

   • Document the gVisor (runsc) IDE companion limitation and troubleshooting guidance.

Related Issues

Fixes #21331

How to Validate

1. Run the targeted unit test suites across core, cli, and vscode-ide-companion:

   npx vitest run --dir packages/core src/ide/ide-gvisor-sandbox.test.ts
   npx vitest run --dir packages/cli src/utils/sandbox.test.ts -t "gVisor|IDE mode"
   npx vitest run --dir packages/vscode-ide-companion src/ide-server.test.ts

2. Verify all gVisor (runsc) and Docker connection scenarios against the compiled IdeClient:
   • Case 1 (GEMINI_SANDBOX=runsc with port and matching workspace path): Reports Failed to connect to IDE companion extension in VS Code: gVisor (runsc) sandboxing enforces strict network isolation which prevents host loopback communication.
   • Case 2 (SANDBOX env var contains runsc): Reports the explicit gVisor network isolation message.
   • Case 3 (GEMINI_SANDBOX=runsc with GEMINI_CLI_IDE_WORKSPACE_PATH unset / host /tmp/gemini/ide port file unmounted in container): Reports the explicit gVisor network isolation message instead of /ide install.
   • Case 4 (GEMINI_SANDBOX=runsc with directory mismatch): Preserves Directory mismatch. error.
   • Case 5 (GEMINI_SANDBOX=runsc with empty workspace ""): Preserves To use this feature, please open a workspace folder in your IDE and try again.
   • Case 6 (GEMINI_SANDBOX=docker when companion server is unreachable): Preserves standard /ide install guidance.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses connectivity issues between the IDE and sandboxed environments, specifically targeting gVisor (runsc) isolation. By ensuring critical environment variables are correctly propagated and updating host header validation, the changes allow for more reliable communication. Additionally, the PR introduces better diagnostics to help users distinguish between configuration errors and inherent sandbox network restrictions.

Highlights

• IDE Sandbox Connectivity: Improved support for containerized IDE sandboxes by forwarding necessary authentication and environment variables to Docker, Podman, and LXC environments.
• gVisor Diagnostic Messaging: Implemented explicit error messaging for gVisor (runsc) environments to clarify that network isolation is the cause of connection failures, replacing generic installation prompts.
• Host Header Validation: Updated the companion server to allow 'host.docker.internal' and 'host.containers.internal' headers, ensuring compatibility with containerized host resolution.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

📊 PR Size: size/L

• Lines changed: 412
• Additions: +398
• Deletions: -14
• Files changed: 9

[gemini-code-assist]

Code Review

This pull request implements forwarding of IDE mode environment variables to LXC and gVisor (runsc) sandbox environments, updates the VS Code companion server to allow container host headers, and improves error reporting for gVisor network isolation. The review feedback highlights a critical security vulnerability where forwarding the sensitive GEMINI_CLI_IDE_AUTH_TOKEN into the sandbox could allow an untrusted process to escape to the host's IDE companion server. Additionally, it is recommended to centralize the gVisor sandbox detection logic into a helper function to avoid scattering environment variable normalization across multiple files.

[elberthc-byte]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds support for forwarding IDE-related environment variables to LXC and gVisor (runsc) sandboxes, and introduces specific error handling for gVisor network isolation when connecting to the IDE companion. Additionally, it updates the VS Code companion server to allow container host headers. Feedback on the changes includes a style guide violation in the tests where process.env is modified directly instead of using vi.stubEnv.

[elberthc-byte]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds support for forwarding IDE mode environment variables (specifically STDIO command and arguments) to LXC and gVisor (runsc) sandboxes. It also handles gVisor's strict network isolation by providing explicit error messages when attempting to connect to the IDE companion extension, and updates the VS Code companion server to allow requests from container host headers (host.docker.internal and host.containers.internal). Comprehensive unit tests have been added to verify these behaviors. I have no feedback to provide as there are no review comments.