{
  "slug": "gemini",
  "url": "/process/gemini/",
  "name": "gemini",
  "kind": "ai-agent",
  "package": "@google/gemini-cli (npm)",
  "binary": "node — the gemini command is a Node.js script (node_modules/@google/gemini-cli/bundle/gemini.js), so ps shows a node process",
  "config": [
    "~/.gemini/settings.json",
    ".gemini/settings.json",
    "~/.gemini/trustedFolders.json",
    ".gemini/.env",
    "~/.gemini/.env"
  ],
  "summary": "Google's Gemini CLI agent: a Node.js process that reads, edits and runs commands in the current project with your user's permissions, approving tools by its approval mode.",
  "symptoms": [
    "a node process at high CPU named after bundle/gemini.js: usually the shell command it launched, so look at its children",
    "edits in files you did not expect: auto_edit or yolo mode, or a tool you allowed 'always'",
    "a Docker or Podman container appearing while it runs: that is its sandbox, which is good"
  ],
  "safe_to_kill": "yes",
  "safe_to_kill_note": "An ordinary user process. Ctrl-C or kill -TERM stops it; a half-written edit or a child command already running is the most it can leave behind, so check git status and git diff afterwards. Killing it does not undo what an earlier approval allowed.",
  "what_it_can_do": "Whatever your Unix user can do, gated by the approval mode. default prompts before every tool that changes something; auto_edit auto-approves the edit tools; plan is read-only; yolo auto-approves every tool and can only be switched on from the command line (--yolo or --approval-mode=yolo), never from a settings file. The starting mode comes from general.defaultApprovalMode in ~/.gemini/settings.json (user) or .gemini/settings.json (workspace overrides user). With folder trust enabled, an untrusted folder runs in safe mode: workspace settings, project .env files, MCP servers, custom commands and tool auto-acceptance are all switched off until you trust it. Deprecated --allowed-tools gives way to the policy engine.",
  "diagnose": [
    {
      "cmd": "ps -eo pid,user,etime,args | grep -E '[g]emini-cli/bundle/gemini.js'",
      "why": "the process is node running gemini.js; the args show --yolo, --approval-mode or --sandbox if they were used"
    },
    {
      "cmd": "ps --ppid \"$(pgrep -f 'bundle/gemini.js' | head -1)\" -o pid,etime,args",
      "why": "its children are the commands and MCP servers it is running right now"
    },
    {
      "cmd": "python3 -c \"import json;d=json.load(open('$HOME/.gemini/settings.json'));print(d.get('general'),d.get('security'),d.get('tools'))\"",
      "why": "approval mode, folder trust, yolo lock-out and sandbox settings in one line; repeat for .gemini/settings.json in the project, which overrides the user file"
    },
    {
      "cmd": "cat ~/.gemini/trustedFolders.json 2>/dev/null",
      "why": "which directories you have trusted; anything you do not recognise deserves a look"
    },
    {
      "cmd": "find ~/.gemini -maxdepth 1 -type f -perm /077 -printf '%m %p\\n'",
      "why": "cached sign-in and API keys live under ~/.gemini; nothing there should be readable by other users"
    },
    {
      "cmd": "ss -tlnp | grep -E 'node|python|uv'",
      "why": "MCP servers a session started and left listening"
    }
  ],
  "fixes": [],
  "harden": [
    {
      "title": "Turn folder trust on, so a cloned repository cannot configure the agent.",
      "note": "security.folderTrust.enabled: true in ~/.gemini/settings.json. The trust prompt appears before any project settings load; /permissions inside the CLI changes a folder's trust later. The list is ~/.gemini/trustedFolders.json (or wherever GEMINI_CLI_TRUSTED_FOLDERS_PATH points)."
    },
    {
      "title": "Lock yolo out on shared machines.",
      "note": "security.disableYoloMode: true makes --yolo a no-op; security.disableAlwaysAllow stops users from granting a tool permanent approval. Both belong in the user settings of every account that runs the CLI."
    },
    {
      "title": "Run the shell commands in a container.",
      "cmd": "GEMINI_SANDBOX=docker gemini -s",
      "note": "-s / --sandbox (or tools.sandbox in settings) runs tool commands inside ghcr.io/google/gemini-cli:latest with Docker or Podman; the project directory is mounted at the same path, the rest of the host is not. On macOS the same flag uses sandbox-exec profiles (permissive-open by default; SEATBELT_PROFILE selects stricter ones). Precedence: flag, then GEMINI_SANDBOX, then settings."
    },
    {
      "title": "One Unix user per agent, secrets out of the environment.",
      "note": "GEMINI_API_KEY and Vertex credentials are read from the environment and from the first .gemini/.env found walking up from the project; a shell command the agent runs can print both. Keep keys in a per-agent account's own ~/.gemini/.env (mode 0600), not in a shared shell profile."
    }
  ],
  "impostors": [
    {
      "cmd": "tr '\\0' ' ' < /proc/$(pgrep -f 'bundle/gemini.js' | head -1)/cmdline; echo",
      "why": "a real one is node running .../@google/gemini-cli/bundle/gemini.js from your npm prefix; a bare binary called gemini under /tmp, /dev/shm or a dot-directory is not this program"
    },
    {
      "cmd": "gemini --version",
      "why": "prints the version number (0.64.0 at the time of writing); a miner has no answer"
    }
  ],
  "listens": [],
  "distros": {
    "any": "Installed with npm install -g @google/gemini-cli; needs Node.js 20 or newer. Container sandbox needs Docker or Podman on Linux; on macOS the built-in sandbox-exec is used instead."
  },
  "applies_to": "Gemini CLI 0.6x on Linux and macOS (facts checked against the project docs on 2026-10-20; flag and settings names change between releases).",
  "see_also": [
    "claude",
    "codex",
    "ollama",
    "openclaw-gateway"
  ],
  "sources": [
    {
      "title": "Gemini CLI docs — Settings (cli/settings.md)",
      "url": "https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/settings.md",
      "fetched": "2026-10-20T00:00:00.000Z"
    },
    {
      "title": "Gemini CLI docs — Sandboxing (cli/sandbox.md)",
      "url": "https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/sandbox.md",
      "fetched": "2026-10-20T00:00:00.000Z"
    },
    {
      "title": "Gemini CLI docs — Trusted folders (cli/trusted-folders.md)",
      "url": "https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/trusted-folders.md",
      "fetched": "2026-10-20T00:00:00.000Z"
    },
    {
      "title": "Gemini CLI docs — Authentication (get-started/authentication.mdx)",
      "url": "https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/authentication.mdx",
      "fetched": "2026-10-20T00:00:00.000Z"
    }
  ],
  "tested_on": "Ubuntu 26.04 · Gemini CLI 0.64.0 via npm (process and flag checks); docs read 2026-10-20",
  "updated": "2026-10-20T00:00:00.000Z",
  "verified": "2026-10-20T00:00:00.000Z",
  "recheck_after": "2026-11-19T00:00:00.000Z",
  "changelog": [
    {
      "date": "2026-10-20T00:00:00.000Z",
      "note": "first version; --allowed-tools is already deprecated in 0.64 in favour of the policy engine"
    }
  ]
}