google-gemini / google-gemini/gemini-cli
Sandbox treats DEBUG=false and DEBUG=0 as enabled
- 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
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