## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The gemini-local adapter runs gemini-cli headlessly, including on
remote/sandboxed execution targets where the adapter manages a dedicated
HOME under the runtime root
> - gemini-cli hard-refuses headless runs with "Invalid auth method
selected." unless `$HOME/.gemini/settings.json` persists an auth
selection; setting `GEMINI_DEFAULT_AUTH_TYPE` alone does NOT satisfy it
(proven in an isolated pod)
> - With a managed HOME the runtime root replaces the image home, so any
settings.json baked into the agent image (or the user's real home) is
invisible to the CLI, and every sandboxed gemini run dies before doing
any work
> - This affects any sandbox provider that runs gemini with API-key auth
through the managed-HOME path (SSH, E2B, Daytona, Kubernetes, or any
other remote execution target); it is a headless-execution bug fix, not
gateway- or deployment-specific behavior
> - This pull request makes the adapter pre-select the `gemini-api-key`
auth type in the managed `$HOME/.gemini/settings.json` whenever a
Gemini/Google API key is present, writing both settings schema
generations and never touching an existing settings.json
> - The benefit is that gemini agents actually run headlessly on remote
and sandboxed execution targets without any manual settings provisioning
## Linked Issues or Issue Description
No existing issue; describing the bug in-PR (bug template fields):
- **What happened:** Headless gemini-local runs on remote/sandboxed
execution targets fail immediately with `Invalid auth method selected.`
even though `GEMINI_API_KEY` is provided.
- **Expected:** Providing the API key should be enough for a headless
run to authenticate and proceed.
- **Root cause:** gemini-cli requires an auth selection persisted in
`$HOME/.gemini/settings.json` for non-interactive runs; the
`GEMINI_DEFAULT_AUTH_TYPE` env var does not substitute for it (verified
in an isolated pod with only the env var set). The adapter's
managed-HOME execution path points HOME at the runtime root, so any
pre-existing settings.json (image-baked or user home) is hidden and the
CLI finds no auth selection.
- **Reproduction:** Run the gemini-local adapter against a
remote/sandboxed execution target with `GEMINI_API_KEY` set and no
settings.json under the managed HOME; the run aborts with the error
above.
- Duplicate/related search: no existing PR or issue addresses this;
closest related is #7693 (bundles gemini-cli in the Docker image), which
makes the CLI available but does not fix headless auth selection.
## What Changed
- `packages/adapters/gemini-local/src/server/execute.ts`: after
provisioning the managed HOME, when a Gemini/Google API key is present,
write `$HOME/.gemini/settings.json` pre-selecting `gemini-api-key` auth.
Both settings schema generations are written (legacy top-level
`selectedAuthType` and current `security.auth.selectedType`) so old and
new gemini-cli versions are covered.
- The write is strictly scoped to the managed HOME (the per-run runtime
root on sandbox transports). On non-managed remote targets (SSH), where
the remote home is the user's real home and existing settings remain
visible to the CLI, the adapter creates nothing (review feedback, P1).
- The write is guarded by `[ -f ... ] ||` so a user-shipped
settings.json (e.g. via workspace) is never overwritten.
- The key-presence gate checks the run env AND the host process env
(`GEMINI_API_KEY` / `GOOGLE_API_KEY`): in sandboxed paths the key never
enters the adapter's run env; it reaches the agent pod via the sandbox
provider's per-run secret (env passthrough from the host env), so the
host env is the correct signal there.
- `packages/adapters/gemini-local/src/server/execute.remote.test.ts`: a
new sandbox-transport test asserts the settings.json write lands under
the per-run runtime root (path + `gemini-api-key` content), and the SSH
test asserts no settings.json is created on a non-managed home.
## Verification
- `npx vitest run packages/adapters/gemini-local`: 3 files, 17 tests,
all pass.
- `pnpm --filter @paperclipai/adapter-gemini-local typecheck` and
`build`: clean (test file is covered by the package tsconfig `include`).
- Negative control: in an isolated pod, gemini-cli with `GEMINI_API_KEY`
+ `GEMINI_DEFAULT_AUTH_TYPE` set but no settings.json still fails with
`Invalid auth method selected.`; with the settings.json written by this
change, the run proceeds.
- Verified end-to-end: a gemini agent in a hardened Kubernetes (gVisor)
sandbox completed a real task (with `GOOGLE_GEMINI_BASE_URL` pointing at
a GenAI-compatible endpoint), producing a billed usage row. That
deployment supplies the verification evidence; the fix applies to any
sandbox provider running gemini with API-key auth.
## Risks
- Low risk. The new write only fires on the managed-HOME path (per-run
runtime root) when an API key is present, and only when no settings.json
exists yet, so existing setups, real user homes on SSH targets, and
user-provided settings are unaffected.
- If a future gemini-cli changes the settings schema again, the file may
need a third generation key; both current generations are written today.
## Model Used
- Claude (Anthropic), Claude Opus 4.8, 1M context, extended thinking,
with tool use (code execution / shell) via Claude Code.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots (no UI change)
- [x] I have updated relevant documentation to reflect my changes (code
comments document the behavior; no doc pages cover managed-home auth)
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
(review requested)
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Jannes Stubbemann
69a368ed51