google-gemini / google-gemini/gemini-cli

Sandbox treats DEBUG=false and DEBUG=0 as enabled

Open
#28,885 2 comments 0 reactions 0 assignees View on GitHub
area/platform status/need-triage
Dominant language
TypeScript
Stars
107k
Forks
14.6k
Avg merge
2d 3h
Merged PRs (30d)
45

Description

### What happened?

Gemini CLI uses two different interpretations of the `DEBUG` environment variable.

The normal CLI configuration and the sandbox entrypoint enable debug mode only for the explicit values `true` and `1`:

```ts
v === 'true' || v === '1'
```

However, `packages/cli/src/utils/sandbox.ts` checks `process.env['DEBUG']` by string truthiness in several places. As a result, values that conventionally disable a flag, such as `DEBUG=false` and `DEBUG=0`, still partially enable sandbox debugging.

For Docker/Podman-style sandboxes, this adds an unnecessary host port publication:

```text
--publish 9229:9229
```

The container entrypoint itself does **not** start the inspector for those values, because `sandboxUtils.ts` correctly checks for `true` or `1`. This leaves the launcher and entrypoint in contradictory states.

For macOS Seatbelt, the same truthy check adds `--inspect-brk` to `NODE_OPTIONS`, which can pause the CLI even though `isDebugMode()` considers debugging disabled.

Other truthy checks in the same file also enable debug console behavior and image-pull logging for `false` and `0`.

### How to reproduce

I added a focused regression test to `packages/cli/src/utils/sandbox.test.ts` that starts the mocked Docker sandbox with each of these values:

```ts
it.each(['false', '0'])(
'should not publish the debug port when DEBUG=%s',
async (debugValue) => {
process.env['DEBUG'] = debugValue;
// start mocked Docker sandbox
// assert docker args exclude --publish and 9229:9229
},
);
```

On current `main`, both cases fail because the Docker arguments contain `--publish 9229:9229`. The remaining 30 tests in `sandbox.test.ts` pass.

### What did you expect to happen?

`DEBUG=false`, `DEBUG=0`, an empty value, and an unset value should all leave debug mode disabled consistently:

- do not inject `--inspect-brk` for Seatbelt;
- do not publish the debugger port for container sandboxes;
- do not enable debug-only console or pull logging.

Only `DEBUG=true`, `DEBUG=1`, or an already-enabled `cliConfig.getDebugMode()` should enable these behaviors.

### Suggested fix

Use one shared boolean parser for `DEBUG` and reuse it in `sandbox.ts`, `sandboxUtils.ts`, and the existing CLI debug-mode calculation. Add coverage for enabled (`true`, `1`) and disabled (`false`, `0`, empty, unset) values.

This is a localized behavior fix with no user-facing API change. I have the regression coverage ready and would be happy to implement it if a maintainer considers it suitable for community contribution and applies the `help wanted` label.

### Client information

- Repository commit: `24cc26ccb`
- Package version: `0.56.0-nightly.20260806.g761f604c1`
- Node.js: `20.19.0`
- OS: macOS (Darwin arm64)

### Anything else we need to know?

No existing open issue or PR matched searches for `DEBUG=false`, `DEBUG=0`, `inspect-brk`, and sandbox debug-port handling at the time of filing.

Contributor guide

Open the contributing guide

Research direction

Start with packages/cli/src/utils/sandbox.ts, packages/cli/src/utils/sandboxUtils.ts, and the existing CLI debug-mode calculation; compare how each interprets DEBUG. Run packages/cli/src/utils/sandbox.test.ts, including the focused false/0 cases, and add coverage for true, 1, empty, and unset values. Done means all debug-only sandbox behavior is enabled consistently only for true, 1, or enabled CLI configuration.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, macos, typescript
Domain
cli, testing
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.