feat(cli): add native gVisor (runsc) sandboxing support (#21062)

Co-authored-by: Zheyuan <zlin252@emory.edu>
Co-authored-by: Kartik Angiras <angiraskartik@gmail.com>

packages/cli/src/config/sandboxConfig.test.ts

@@ -97,7 +97,7 @@ describe('loadSandboxConfig', () => {
     it('should throw if GEMINI_SANDBOX is an invalid command', async () => {
       process.env['GEMINI_SANDBOX'] = 'invalid-command';
       await expect(loadSandboxConfig({}, {})).rejects.toThrow(
-        "Invalid sandbox command 'invalid-command'. Must be one of docker, podman, sandbox-exec, lxc",
+        "Invalid sandbox command 'invalid-command'. Must be one of docker, podman, sandbox-exec, runsc, lxc",
       );
     });
 
@@ -194,7 +194,7 @@ describe('loadSandboxConfig', () => {
       await expect(
         loadSandboxConfig({}, { sandbox: 'invalid-command' }),
       ).rejects.toThrow(
-        "Invalid sandbox command 'invalid-command'. Must be one of docker, podman, sandbox-exec",
+        "Invalid sandbox command 'invalid-command'. Must be one of docker, podman, sandbox-exec, runsc, lxc",
       );
     });
   });
@@ -247,4 +247,92 @@ describe('loadSandboxConfig', () => {
       },
     );
   });
+
+  describe('with sandbox: runsc (gVisor)', () => {
+    beforeEach(() => {
+      mockedOsPlatform.mockReturnValue('linux');
+      mockedCommandExistsSync.mockReturnValue(true);
+    });
+
+    it('should use runsc via CLI argument on Linux', async () => {
+      const config = await loadSandboxConfig({}, { sandbox: 'runsc' });
+
+      expect(config).toEqual({ command: 'runsc', image: 'default/image' });
+      expect(mockedCommandExistsSync).toHaveBeenCalledWith('runsc');
+      expect(mockedCommandExistsSync).toHaveBeenCalledWith('docker');
+    });
+
+    it('should use runsc via GEMINI_SANDBOX environment variable', async () => {
+      process.env['GEMINI_SANDBOX'] = 'runsc';
+      const config = await loadSandboxConfig({}, {});
+
+      expect(config).toEqual({ command: 'runsc', image: 'default/image' });
+      expect(mockedCommandExistsSync).toHaveBeenCalledWith('runsc');
+      expect(mockedCommandExistsSync).toHaveBeenCalledWith('docker');
+    });
+
+    it('should use runsc via settings file', async () => {
+      const config = await loadSandboxConfig(
+        { tools: { sandbox: 'runsc' } },
+        {},
+      );
+
+      expect(config).toEqual({ command: 'runsc', image: 'default/image' });
+      expect(mockedCommandExistsSync).toHaveBeenCalledWith('runsc');
+      expect(mockedCommandExistsSync).toHaveBeenCalledWith('docker');
+    });
+
+    it('should prioritize GEMINI_SANDBOX over CLI and settings', async () => {
+      process.env['GEMINI_SANDBOX'] = 'runsc';
+      const config = await loadSandboxConfig(
+        { tools: { sandbox: 'docker' } },
+        { sandbox: 'podman' },
+      );
+
+      expect(config).toEqual({ command: 'runsc', image: 'default/image' });
+    });
+
+    it('should reject runsc on macOS (Linux-only)', async () => {
+      mockedOsPlatform.mockReturnValue('darwin');
+
+      await expect(loadSandboxConfig({}, { sandbox: 'runsc' })).rejects.toThrow(
+        'gVisor (runsc) sandboxing is only supported on Linux',
+      );
+    });
+
+    it('should reject runsc on Windows (Linux-only)', async () => {
+      mockedOsPlatform.mockReturnValue('win32');
+
+      await expect(loadSandboxConfig({}, { sandbox: 'runsc' })).rejects.toThrow(
+        'gVisor (runsc) sandboxing is only supported on Linux',
+      );
+    });
+
+    it('should throw if runsc binary not found', async () => {
+      mockedCommandExistsSync.mockReturnValue(false);
+
+      await expect(loadSandboxConfig({}, { sandbox: 'runsc' })).rejects.toThrow(
+        "Missing sandbox command 'runsc' (from GEMINI_SANDBOX)",
+      );
+    });
+
+    it('should throw if Docker not available (runsc requires Docker)', async () => {
+      mockedCommandExistsSync.mockImplementation((cmd) => cmd === 'runsc');
+
+      await expect(loadSandboxConfig({}, { sandbox: 'runsc' })).rejects.toThrow(
+        "runsc (gVisor) requires Docker. Install Docker, or use sandbox: 'docker'.",
+      );
+    });
+
+    it('should NOT auto-detect runsc when both runsc and docker available', async () => {
+      mockedCommandExistsSync.mockImplementation(
+        (cmd) => cmd === 'runsc' || cmd === 'docker',
+      );
+
+      const config = await loadSandboxConfig({}, { sandbox: true });
+
+      expect(config?.command).toBe('docker');
+      expect(config?.command).not.toBe('runsc');
+    });
+  });
 });

packages/cli/src/config/sandboxConfig.ts

@@ -27,6 +27,7 @@ const VALID_SANDBOX_COMMANDS: ReadonlyArray<SandboxConfig['command']> = [
   'docker',
   'podman',
   'sandbox-exec',
+  'runsc',
   'lxc',
 ];
 
@@ -64,17 +65,30 @@ function getSandboxCommand(
         )}`,
       );
     }
-    // confirm that specified command exists
-    if (commandExists.sync(sandbox)) {
-      return sandbox;
+    // runsc (gVisor) is only supported on Linux
+    if (sandbox === 'runsc' && os.platform() !== 'linux') {
+      throw new FatalSandboxError(
+        'gVisor (runsc) sandboxing is only supported on Linux',
+      );
     }
-    throw new FatalSandboxError(
-      `Missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)`,
-    );
+    // confirm that specified command exists
+    if (!commandExists.sync(sandbox)) {
+      throw new FatalSandboxError(
+        `Missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)`,
+      );
+    }
+    // runsc uses Docker with --runtime=runsc; both must be available (prioritize runsc when explicitly chosen)
+    if (sandbox === 'runsc' && !commandExists.sync('docker')) {
+      throw new FatalSandboxError(
+        "runsc (gVisor) requires Docker. Install Docker, or use sandbox: 'docker'.",
+      );
+    }
+    return sandbox;
   }
 
   // look for seatbelt, docker, or podman, in that order
   // for container-based sandboxing, require sandbox to be enabled explicitly
+  // note: runsc is NOT auto-detected, it must be explicitly specified
   if (os.platform() === 'darwin' && commandExists.sync('sandbox-exec')) {
     return 'sandbox-exec';
   } else if (commandExists.sync('docker') && sandbox === true) {