{"record":{"id":"db15867bd6e67fc9","repo":"google-gemini/gemini-cli","slug":"gvisor-runsc-sandboxing-is-only-supported-on-lin","errorCode":null,"errorMessage":"gVisor (runsc) sandboxing is only supported on Linux","messagePattern":"gVisor \\(runsc\\) sandboxing is only supported on Linux","errorType":"exception","errorClass":"FatalSandboxError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/config/sandboxConfig.ts","lineNumber":75,"sourceCode":"      : sandbox;\n  if (sandbox === '1' || sandbox === 'true') sandbox = true;\n  else if (sandbox === '0' || sandbox === 'false' || !sandbox) sandbox = false;\n\n  if (sandbox === false) {\n    return '';\n  }\n\n  if (typeof sandbox === 'string' && sandbox) {\n    if (!isSandboxCommand(sandbox)) {\n      throw new FatalSandboxError(\n        `Invalid sandbox command '${sandbox}'. Must be one of ${VALID_SANDBOX_COMMANDS.join(\n          ', ',\n        )}`,\n      );\n    }\n    // runsc (gVisor) is only supported on Linux\n    if (sandbox === 'runsc' && os.platform() !== 'linux') {\n      throw new FatalSandboxError(\n        'gVisor (runsc) sandboxing is only supported on Linux',\n      );\n    }\n    // windows-native is only supported on Windows\n    if (sandbox === 'windows-native' && os.platform() !== 'win32') {\n      throw new FatalSandboxError(\n        'Windows native sandboxing is only supported on Windows',\n      );\n    }\n\n    // confirm that specified command exists (unless it's built-in)\n    if (sandbox !== 'windows-native' && !commandExists.sync(sandbox)) {\n      throw new FatalSandboxError(\n        `Missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)`,\n      );\n    }\n    // runsc uses Docker with --runtime=runsc; both must be available (prioritize runsc when explicitly chosen)\n    if (sandbox === 'runsc' && !commandExists.sync('docker')) {","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/cli/src/config/sandboxConfig.ts#L57-L93","documentation":"Thrown as FatalSandboxError when sandbox is set to 'runsc' (gVisor) but os.platform() is not 'linux'. gVisor's runsc runtime is a Linux kernel-level sandbox, so on macOS/Windows the configuration is impossible and is rejected before any command lookup.","triggerScenarios":"GEMINI_SANDBOX=runsc or sandbox='runsc' on macOS or Windows.","commonSituations":"Shared dotfiles/env exporting GEMINI_SANDBOX=runsc applied on a non-Linux machine; CI matrix running the same env on multiple OSes.","solutions":["On macOS use sandbox-exec (or docker); on Windows use windows-native; remove the runsc setting on non-Linux.","Make the sandbox choice platform-conditional in your shell rc / CI config.","Unset GEMINI_SANDBOX to fall back to auto-detection."],"exampleFix":"// before\nexport GEMINI_SANDBOX=runsc   # on macOS\n// after\ncase \"$(uname -s)\" in Linux) export GEMINI_SANDBOX=runsc;; esac","handlingStrategy":"validation","validationCode":"function canUseRunsc(): boolean { return os.platform() === 'linux'; }","typeGuard":"function runscSupported(): boolean { return os.platform() === 'linux'; }","tryCatchPattern":null,"preventionTips":["Only export GEMINI_SANDBOX=runsc on Linux hosts.","Make sandbox selection platform-conditional in shared dotfiles."],"tags":["sandbox","platform","config","fatal"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}