Quickstart: Gemini in Workcell

August 5, 2026 ยท View on GitHub

This guide assumes a supported Apple Silicon macOS host. GitHub-hosted CI and tagged-release install verification currently cover macos-26 and macos-15; the strongest local boundary claim still depends on local Colima validation.

Prerequisites

  • Workcell installed with ./scripts/install.sh
  • a repo you want to mount as the workspace
  • either a reviewed Gemini env file or reviewed cached OAuth material

1. Create or update the injection policy

Gemini Code Assist (GCA), API key, or Vertex environment file path:

workcell auth init
workcell auth set \
  --agent gemini \
  --credential gemini_env \
  --source /Users/example/.config/workcell/gemini.env

Cached OAuth path:

workcell auth set \
  --agent gemini \
  --credential gemini_oauth \
  --source /Users/example/.config/workcell/gemini-oauth.json

2. Optional explicit prepare

A normal strict launch prepares the reviewed runtime image automatically when needed:

workcell --agent gemini --workspace /path/to/repo

Use --prepare-only when you want to prewarm without launching:

workcell --prepare-only --agent gemini --workspace /path/to/repo

3. Inspect the derived posture

workcell --agent gemini --doctor --workspace /path/to/repo
workcell --agent gemini --inspect --workspace /path/to/repo
workcell auth status --agent gemini
workcell --agent gemini --auth-status --workspace /path/to/repo

The gemini_env and gemini_oauth paths report provider_bootstrap_path=direct-staged. The gemini_projects path reports provider_bootstrap_state=supplemental-only. The project registry is not an auth mode. The gcloud_adc input is also a Vertex supplement. See docs/examples/gemini-vertex-setup.md and docs/provider-bootstrap-matrix.md for the current manual handoff.

4. Launch Gemini

workcell --agent gemini --workspace /path/to/repo

Gemini's trusted-folders registry is seeded on the managed path so /workspace is already trusted inside the ephemeral session home.

Managed development lane:

workcell --agent gemini --mode development --workspace /path/to/repo -- bash -lc 'npm test'

5. Vertex supplement

If the env file configures Vertex and you need ADC as a supplemental input:

workcell auth set \
  --agent gemini \
  --credential gcloud_adc \
  --source /Users/example/.config/workcell/gcloud-adc.json

6. Publish the result on the host

./scripts/pre-merge.sh --profile pr-parity
./scripts/repo-publish-pr.sh --workspace /path/to/repo --branch feature/my-change \
  --title-file /tmp/pr-title.txt --body-file /tmp/pr-body.md \
  --commit-message-file /tmp/commit-message.txt

Further reading