{"record":{"id":"9ba4c318aa12a26f","repo":"google-gemini/gemini-cli","slug":"runsc-gvisor-requires-docker-install-docker-or","errorCode":null,"errorMessage":"runsc (gVisor) requires Docker. Install Docker, or use sandbox: 'docker'.","messagePattern":"runsc \\(gVisor\\) requires Docker\\. Install Docker, or use sandbox: 'docker'\\.","errorType":"exception","errorClass":"FatalSandboxError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/config/sandboxConfig.ts","lineNumber":94,"sourceCode":"        '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')) {\n      throw new FatalSandboxError(\n        \"runsc (gVisor) requires Docker. Install Docker, or use sandbox: 'docker'.\",\n      );\n    }\n    return sandbox;\n  }\n\n  // look for seatbelt, docker, or podman, in that order\n  // for container-based sandboxing, require sandbox to be enabled explicitly\n  // note: runsc is NOT auto-detected, it must be explicitly specified\n  if (os.platform() === 'darwin' && commandExists.sync('sandbox-exec')) {\n    return 'sandbox-exec';\n  } else if (commandExists.sync('docker') && sandbox === true) {\n    return 'docker';\n  } else if (commandExists.sync('podman') && sandbox === true) {\n    return 'podman';\n  }\n\n  // throw an error if user requested sandbox but no command was found","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/cli/src/config/sandboxConfig.ts#L76-L112","documentation":"Thrown as FatalSandboxError when sandbox is 'runsc' and commandExists.sync('docker') is false. gVisor's runsc is used as a Docker runtime (--runtime=runsc), so even on Linux both the runsc binary and Docker must be present; the error steers the user to install Docker or fall back to plain docker sandboxing.","triggerScenarios":"GEMINI_SANDBOX=runsc on Linux where runsc is installed but Docker is not (or docker is not on PATH).","commonSituations":"runsc installed for testing without a Docker engine; minimal VM/container that has runsc but not dockerd; Docker binary renamed or not on PATH.","solutions":["Install Docker (engine + CLI) and ensure 'docker' is on PATH.","If Docker is unavailable, switch to GEMINI_SANDBOX=podman or remove the sandbox setting.","Verify with 'docker info' that the daemon is reachable before retrying."],"exampleFix":"// before\nexport GEMINI_SANDBOX=runsc   # no docker installed\n// after\nsudo apt-get install docker.io && export GEMINI_SANDBOX=runsc","handlingStrategy":"validation","validationCode":"import commandExists from 'command-exists';\nfunction runscReady(): boolean { return os.platform() === 'linux' && commandExists.sync('runsc') && commandExists.sync('docker'); }","typeGuard":"function runscReady(): boolean { return commandExists.sync('docker') && commandExists.sync('runsc'); }","tryCatchPattern":null,"preventionTips":["Install Docker when selecting runsc, or switch to GEMINI_SANDBOX=docker.","Verify 'docker info' works before relying on runsc."],"tags":["sandbox","docker","gvisor","config","fatal"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}