google-gemini/gemini-cli · error · FatalSandboxError

gVisor (runsc) sandboxing is only supported on Linux

Error message

gVisor (runsc) sandboxing is only supported on Linux

What it means

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.

Source

Thrown at packages/cli/src/config/sandboxConfig.ts:75

      : sandbox;
  if (sandbox === '1' || sandbox === 'true') sandbox = true;
  else if (sandbox === '0' || sandbox === 'false' || !sandbox) sandbox = false;

  if (sandbox === false) {
    return '';
  }

  if (typeof sandbox === 'string' && sandbox) {
    if (!isSandboxCommand(sandbox)) {
      throw new FatalSandboxError(
        `Invalid sandbox command '${sandbox}'. Must be one of ${VALID_SANDBOX_COMMANDS.join(
          ', ',
        )}`,
      );
    }
    // runsc (gVisor) is only supported on Linux
    if (sandbox === 'runsc' && os.platform() !== 'linux') {
      throw new FatalSandboxError(
        'gVisor (runsc) sandboxing is only supported on Linux',
      );
    }
    // windows-native is only supported on Windows
    if (sandbox === 'windows-native' && os.platform() !== 'win32') {
      throw new FatalSandboxError(
        'Windows native sandboxing is only supported on Windows',
      );
    }

    // confirm that specified command exists (unless it's built-in)
    if (sandbox !== 'windows-native' && !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')) {

View on GitHub (pinned to 5024443c72)

Solutions

1. On macOS use sandbox-exec (or docker); on Windows use windows-native; remove the runsc setting on non-Linux.
2. Make the sandbox choice platform-conditional in your shell rc / CI config.
3. Unset GEMINI_SANDBOX to fall back to auto-detection.

Example fix

// before
export GEMINI_SANDBOX=runsc   # on macOS
// after
case "$(uname -s)" in Linux) export GEMINI_SANDBOX=runsc;; esac

function canUseRunsc(): boolean { return os.platform() === 'linux'; }

function runscSupported(): boolean { return os.platform() === 'linux'; }

When it happens

Trigger: GEMINI_SANDBOX=runsc or sandbox='runsc' on macOS or Windows.

Common situations: Shared dotfiles/env exporting GEMINI_SANDBOX=runsc applied on a non-Linux machine; CI matrix running the same env on multiple OSes.

Related errors

• Windows native sandboxing is only supported on Windows
• Invalid sandbox command '${sandbox}'. Must be one of ${VALID
• Missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)
• runsc (gVisor) requires Docker. Install Docker, or use sandb
• Workspace path ${resolvedPath} is outside the allowed root d

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/db15867bd6e67fc9. Report an issue: GitHub.