fix(companion): allow IPC socket fallback for gVisor/runsc sandboxes by elberthc-byte · Pull Request #29597 · google-gemini/gemini-cli

elberthc-byte · 2026-10-02T01:05:27Z

Summary

Allows IPC fallback and fixes container host/token configuration for sandboxed environments. In gVisor (GEMINI_SANDBOX=runsc), user-space Netstack isolates the container loopback interface and blocks communication with the host's loopback (127.0.0.1). This PR enables stdio IPC fallback by propagating GEMINI_CLI_IDE_SERVER_STDIO_* and GEMINI_CLI_IDE_AUTH_TOKEN into sandbox containers, allows container host headers (host.docker.internal and host.containers.internal) in ide-server.ts, and adds informative diagnostic details when running under gVisor instead of misleading the user to reinstall the extension.

Details

Environment Variable Propagation: Updated packages/cli/src/utils/sandbox.ts to forward GEMINI_CLI_IDE_AUTH_TOKEN, GEMINI_CLI_IDE_SERVER_STDIO_COMMAND, and GEMINI_CLI_IDE_SERVER_STDIO_ARGS alongside existing IDE environment variables.
Host Validation Adjustment: Updated packages/vscode-ide-companion/src/ide-server.ts to allow host.docker.internal:${this.port} and host.containers.internal:${this.port} in allowedHosts, enabling containerized environments that support host-gateway routing (e.g. Docker Desktop) to authenticate without receiving HTTP 403 Forbidden.
gVisor Isolation Diagnostics: Updated packages/core/src/ide/ide-client.ts to detect runsc sandboxing and report that gVisor's network isolation boundary prevents host loopback communication when connection fails, rather than recommending /ide install.
Test Coverage:
- packages/cli/src/utils/sandbox.test.ts: Verifies pass-through of all IDE environment variables into container execution arguments.
- packages/vscode-ide-companion/src/ide-server.test.ts: Verifies that host.docker.internal and host.containers.internal are accepted Host headers.
- packages/core/src/ide/ide-gvisor-sandbox.test.ts: Verifies Netstack gateway refusal, missing/blocked IPC Unix socket path (--host-uds=none), and gVisor isolation diagnostics.

Related Issues

Fixes #21331

How to Validate

Unit Tests

npm test -w @google/gemini-cli-core -- src/ide/ide-gvisor-sandbox.test.ts src/ide/ide-client.test.ts src/ide/ide-connection-utils.test.ts
npm test -w gemini-cli-vscode-ide-companion -- src/ide-server.test.ts
npm test -w @google/gemini-cli -- -t "should pass through all IDE environment variables into container args" src/utils/sandbox.test.ts

Manual Verification & Reproduction Steps

1. Steps to Reproduce the Issue:

Run VS Code with the Gemini CLI Companion extension active on Linux.
Launch Gemini CLI inside a gVisor sandbox:
```
GEMINI_SANDBOX=runsc gemini
```
Run /ide status.
Observed Failure: The connection fails with Failed to connect to IDE companion extension in VS Code. Please ensure the extension is running. To install the extension, run /ide install., and GEMINI_CLI_IDE_AUTH_TOKEN is dropped from the container environment.

2. Validate the Solution:

Launch Gemini CLI inside a gVisor sandbox:
```
GEMINI_SANDBOX=runsc gemini
```
Run /ide status.
- Expected Result: Reports accurate diagnostic: Failed to connect to IDE companion extension in VS Code: gVisor (runsc) sandboxing enforces strict network isolation which prevents host loopback communication.
Validate Stdio IPC Fallback:
Configure a stdio IPC command in the environment:
```
export GEMINI_CLI_IDE_SERVER_STDIO_COMMAND="/path/to/stdio-mcp-bridge"
export GEMINI_CLI_IDE_SERVER_STDIO_ARGS='["--stdio"]'
GEMINI_SANDBOX=runsc gemini
```
- Expected Result: Environment variables are forwarded into the container and IdeClient connects via stdio stream transport.
Validate Container Host Gateway (Docker Desktop):
In an environment with host.docker.internal resolution, connect to http://host.docker.internal:${port}/mcp.
- Expected Result: The companion server accepts the Host header and validates the forwarded GEMINI_CLI_IDE_AUTH_TOKEN.

Pre-Merge Checklist

gemini-code-assist · 2026-10-02T01:05:37Z

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 improves the Gemini CLI's compatibility with sandboxed environments, specifically gVisor (runsc). It addresses network isolation challenges by implementing stdio IPC fallback, allowing host-gateway headers for authentication, and providing clearer diagnostic feedback when connection attempts are blocked by sandbox constraints.

Highlights

IPC Fallback Support: Enabled stdio IPC fallback by propagating necessary environment variables (auth token, command, and arguments) into sandboxed containers.
Container Host Header Support: Updated the IDE server to allow 'host.docker.internal' and 'host.containers.internal' in host headers, improving compatibility with containerized environments.
Improved Diagnostics: Added specific error messaging for gVisor (runsc) environments to clarify that connection failures are due to network isolation rather than installation issues.

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.

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 · 2026-10-02T01:05:41Z

📊 PR Size: size/L

Lines changed: 279
Additions: +277
Deletions: -2
Files changed: 6

gemini-code-assist

Code Review

This pull request improves the IDE companion's compatibility with gVisor (runsc) sandboxing by forwarding additional IDE environment variables to the sandbox container, allowing container-specific host headers, and adding a detailed diagnostic message for connection failures under network isolation. The review feedback points out a critical issue where the GEMINI_SANDBOX environment variable is not forwarded to the container, which would prevent the gVisor detection logic from working inside the sandbox, and provides actionable code suggestions to resolve this in both the implementation and the tests.

elberthc-byte · 2026-10-02T18:16:04Z

/gemini review

gemini-code-assist

Code Review

This pull request adds support for passing through additional IDE environment variables into container arguments, improves connection failure messaging under gVisor sandboxing, and allows host.docker.internal and host.containers.internal host headers in the VS Code IDE companion server. Feedback suggests normalizing the incoming Host header to lowercase to prevent case-sensitivity issues and removing a redundant, misleading test in ide-gvisor-sandbox.test.ts that uses an inverted assertion anti-pattern.

elberthc-byte · 2026-10-02T19:50:04Z

/gemini review

gemini-code-assist

Code Review

This pull request updates the sandbox utility to propagate additional IDE environment variables (including GEMINI_CLI_IDE_AUTH_TOKEN) into the container, adds gVisor network isolation detection with descriptive error messages, and allows container-specific Host headers (host.docker.internal and host.containers.internal) in the VS Code IDE companion server. However, the review highlights a critical security vulnerability where propagating the sensitive authentication token into an untrusted sandbox, combined with allowing container-to-host communication, enables a complete sandbox escape. To remediate this, it is recommended to avoid passing the token to the sandbox or to enforce strict path validation on the IDE companion server to prevent unauthorized access to host files.

elberthc-byte · 2026-10-02T19:54:21Z

/gemini review

gemini-code-assist

Code Review

This pull request adds support for gVisor (runsc) sandboxing by passing additional IDE environment variables to the sandbox container, improving connection failure details when gVisor network isolation is detected, and allowing container-specific host headers (host.docker.internal and host.containers.internal) in the VS Code IDE companion server. The feedback suggests improving the test mocks in ide-gvisor-sandbox.test.ts by making the module-level fs.existsSync mock conditional rather than completely overriding it in individual test cases, preventing fragile test behavior.

elberthc-byte · 2026-10-02T20:20:38Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces support for running the IDE companion within gVisor (runsc) and containerized sandboxes by propagating relevant environment variables, allowing container host headers, and providing descriptive error messages upon connection failures. However, two critical issues must be addressed: first, forwarding the sensitive GEMINI_CLI_IDE_AUTH_TOKEN into the sandbox container poses a high security risk of sandbox escape by untrusted code; second, accessing this.currentIde.displayName in ide-client.ts is unsafe and could lead to a runtime TypeError if the property is undefined.

…o ide-client

elberthc-byte · 2026-10-02T20:40:11Z

/gemini review

gemini-code-assist

Code Review

This pull request adds support for gVisor (runsc) sandboxing constraints by propagating additional IDE environment variables to the sandbox container, updating the IdeClient to provide detailed error messages under network isolation, and allowing container-specific host headers in the companion server. The review feedback highlights a critical missing environment variable, GEMINI_CLI_IDE_AUTH_TOKEN, which must be propagated to the container for proper authentication, along with corresponding test assertions. Additionally, it is recommended to mock fs.promises.open in the sandbox tests to ensure they remain fully hermetic.

elberthc-byte · 2026-10-02T21:05:00Z

/gemini review

gemini-code-assist

Code Review

This pull request adds support for running the IDE companion under gVisor (runsc) sandbox constraints by forwarding necessary environment variables to the sandbox container, updating connection failure diagnostics with gVisor-specific details, and allowing container-specific host headers (like host.docker.internal) in the companion server. The review feedback highlights a critical omission: the GEMINI_CLI_IDE_AUTH_TOKEN environment variable must be forwarded to prevent authentication failures, and corresponding test coverage should be added. Additionally, the feedback suggests ensuring GEMINI_SANDBOX is correctly forwarded when configured via settings.json (i.e., when config.command is 'runsc').

elberthc-byte · 2026-10-02T21:35:39Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces support for running the IDE companion under gVisor (runsc) sandbox constraints. It forwards additional IDE environment variables to the sandbox container, updates the IDE client to display informative error messages regarding network isolation under gVisor, and allows container-specific host headers in the IDE server. The review feedback correctly identifies that GEMINI_CLI_IDE_AUTH_TOKEN was omitted from the list of propagated environment variables in start_sandbox and its corresponding test, which would cause authentication failures.

elberthc-byte · 2026-10-02T22:06:03Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces changes to support running the IDE companion under gVisor (runsc) sandbox constraints. It forwards additional IDE-related environment variables to the sandbox container, allows container-specific host headers (such as host.docker.internal and host.containers.internal) in the VS Code companion server, and improves error reporting when network isolation prevents loopback communication. The review feedback correctly identifies that GEMINI_CLI_IDE_AUTH_TOKEN is missing from the list of forwarded environment variables in sandbox.ts, which is critical to prevent authentication failures (401 Unauthorized) inside the sandbox.

elberthc-byte · 2026-10-02T23:57:25Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces support for running the IDE companion under gVisor (runsc) sandbox constraints by forwarding additional environment variables, improving connection failure messages with gVisor-specific details, and allowing container-specific host headers in the IDE server. The review feedback identifies that the GEMINI_CLI_IDE_AUTH_TOKEN environment variable is missing from the forwarded variables list, which would cause authentication failures, and provides suggestions to propagate and test this token.

gemini-code-assist · 2026-10-03T00:00:12Z

    for (const envVar of [
      'GEMINI_CLI_IDE_SERVER_PORT',
      'GEMINI_CLI_IDE_WORKSPACE_PATH',
+      'GEMINI_CLI_IDE_SERVER_STDIO_COMMAND',
+      'GEMINI_CLI_IDE_SERVER_STDIO_ARGS',
      'TERM_PROGRAM',
+      'GEMINI_SANDBOX',
    ]) {


The environment variable GEMINI_CLI_IDE_AUTH_TOKEN is missing from the list of forwarded variables. Without propagating this token, the containerized CLI will fail to authenticate with the host companion server (resulting in 401 Unauthorized errors) when attempting to connect via HTTP (e.g., using host.docker.internal). Please add GEMINI_CLI_IDE_AUTH_TOKEN to the list of forwarded environment variables.

for (const envVar of [ 'GEMINI_CLI_IDE_SERVER_PORT', 'GEMINI_CLI_IDE_WORKSPACE_PATH', 'GEMINI_CLI_IDE_SERVER_STDIO_COMMAND', 'GEMINI_CLI_IDE_SERVER_STDIO_ARGS', 'GEMINI_CLI_IDE_AUTH_TOKEN', 'TERM_PROGRAM', 'GEMINI_SANDBOX', ]) {

gemini-code-assist · 2026-10-03T00:00:12Z

+    it('should pass through all IDE environment variables into container args', async () => {
+      vi.stubEnv('GEMINI_CLI_IDE_SERVER_PORT', '9999');
+      vi.stubEnv('GEMINI_CLI_IDE_WORKSPACE_PATH', '/test/workspace');
+      vi.stubEnv('GEMINI_CLI_IDE_SERVER_STDIO_COMMAND', '/usr/bin/ide-bridge');
+      vi.stubEnv('GEMINI_CLI_IDE_SERVER_STDIO_ARGS', '["--flag"]');
+      vi.stubEnv('TERM_PROGRAM', 'vscode');
+      vi.stubEnv('GEMINI_SANDBOX', 'runsc');


Stub the GEMINI_CLI_IDE_AUTH_TOKEN environment variable in the test to verify its propagation into the container arguments.

Suggested change

it('should pass through all IDE environment variables into container args', async () => {

vi.stubEnv('GEMINI_CLI_IDE_SERVER_PORT', '9999');

vi.stubEnv('GEMINI_CLI_IDE_WORKSPACE_PATH', '/test/workspace');

vi.stubEnv('GEMINI_CLI_IDE_SERVER_STDIO_COMMAND', '/usr/bin/ide-bridge');

vi.stubEnv('GEMINI_CLI_IDE_SERVER_STDIO_ARGS', '["--flag"]');

vi.stubEnv('TERM_PROGRAM', 'vscode');

vi.stubEnv('GEMINI_SANDBOX', 'runsc');

it('should pass through all IDE environment variables into container args', async () => {

vi.stubEnv('GEMINI_CLI_IDE_SERVER_PORT', '9999');

vi.stubEnv('GEMINI_CLI_IDE_WORKSPACE_PATH', '/test/workspace');

vi.stubEnv('GEMINI_CLI_IDE_SERVER_STDIO_COMMAND', '/usr/bin/ide-bridge');

vi.stubEnv('GEMINI_CLI_IDE_SERVER_STDIO_ARGS', '["--flag"]');

vi.stubEnv('GEMINI_CLI_IDE_AUTH_TOKEN', 'test-auth-token');

vi.stubEnv('TERM_PROGRAM', 'vscode');

vi.stubEnv('GEMINI_SANDBOX', 'runsc');

gemini-code-assist · 2026-10-03T00:00:12Z

+        expect.arrayContaining([
+          '--env',
+          'GEMINI_CLI_IDE_SERVER_PORT=9999',
+          '--env',
+          'GEMINI_CLI_IDE_WORKSPACE_PATH=/test/workspace',
+          '--env',
+          'GEMINI_CLI_IDE_SERVER_STDIO_COMMAND=/usr/bin/ide-bridge',
+          '--env',
+          'GEMINI_CLI_IDE_SERVER_STDIO_ARGS=["--flag"]',
+          '--env',
+          'TERM_PROGRAM=vscode',
+          '--env',
+          'GEMINI_SANDBOX=runsc',
+        ]),


Update the assertion to verify that GEMINI_CLI_IDE_AUTH_TOKEN is correctly passed as an environment variable to the container.

expect.arrayContaining([ '--env', 'GEMINI_CLI_IDE_SERVER_PORT=9999', '--env', 'GEMINI_CLI_IDE_WORKSPACE_PATH=/test/workspace', '--env', 'GEMINI_CLI_IDE_SERVER_STDIO_COMMAND=/usr/bin/ide-bridge', '--env', 'GEMINI_CLI_IDE_SERVER_STDIO_ARGS=["--flag"]', '--env', 'GEMINI_CLI_IDE_AUTH_TOKEN=test-auth-token', '--env', 'TERM_PROGRAM=vscode', '--env', 'GEMINI_SANDBOX=runsc', ]),

fix(companion): allow IPC socket fallback for gVisor/runsc sandboxes

c927683

elberthc-byte requested a review from a team as a code owner October 2, 2026 01:05

github-actions Bot added the size/l A large sized PR label Oct 2, 2026