molecule-ai/molecule-ai-workspace-template-gemini-cli

Molecule AI Plugin-Dev 65c6a3ae05 docs: add CLAUDE.md, known-issues.md, and runbooks/local-dev-setup.md

2026-04-21 10:55:10 +00:00

5.9 KiB

Raw Blame History

Local Dev Setup Runbook

This runbook covers setting up the gemini-cli workspace template on a local machine for development and testing. Follow each step in order.

Prerequisites

Python 3.11+
Docker 24.0+
A valid Gemini API key (from Google AI Studio or Google Cloud)
Git

Step 1: Clone the Repository

git clone https://github.com/molecule-ai/molecule-ai-workspace-template-gemini-cli.git
cd molecule-ai-workspace-template-gemini-cli

Step 2: Install Python Dependencies

Create a virtual environment and install the pinned dependencies:

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Expected output:

Collecting gemini-cli>=1.0.0
  Downloading gemini_cli-1.2.1-py3-none-any.whl (2.1 MB)
Collecting molecule-ai-adapter>=2.1.0
  Downloading molecule_ai_adapter-2.3.0-py3-none-any.whl (650 kB)
...
Installing collected packages: gemini-cli, molecule-ai-adapter, httpx, pydantic
Successfully installed gemini-cli-1.2.1 molecule-ai-adapter-2.3.0 httpx-0.27.2 pydantic-2.9.2

Step 3: Set Your API Key

Store your Gemini API key in a local file (never commit this file):

# Replace with your actual key from https://aistudio.google.com/apikey
echo "AIzaSy..." > ~/.gemini-api-key
chmod 600 ~/.gemini-api-key

Set the env var for the current session:

export GEMINI_API_KEY="$(cat ~/.gemini-api-key)"

Step 4: Build the Docker Image

docker build -t molecule-gemini-cli:dev .

To include the API key at build time (buildkit only — do not do this in CI or shared machines):

DOCKER_BUILDKIT=1 docker build \
  --build-arg GEMINI_API_KEY="$GEMINI_API_KEY" \
  -t molecule-gemini-cli:dev \
  .

Standard build without build-time secret:

docker build -t molecule-gemini-cli:dev .

Step 5: Config Override for Local Dev

The template reads config.yaml for runtime settings. For local dev, override settings via environment variables or by editing a local copy.

Option A — environment variables (recommended for dev):

export WORKSPACE_ID="dev-local"
export ADAPTER_PLATFORM_URL="https://platform.molecule.ai"
export GEMINI_API_KEY="$(cat ~/.gemini-api-key)"

Option B — local config file override:

# Work on a copy, never modify config.yaml directly
cp config.yaml config.yaml.local
$EDITOR config.yaml.local

Then run the container with the local config mounted:

docker run --rm \
  -e GEMINI_API_KEY="$GEMINI_API_KEY" \
  -e WORKSPACE_ID="dev-local" \
  -v "$(pwd)/config.yaml.local:/workspace/config.yaml:ro" \
  molecule-gemini-cli:dev

Step 6: Docker Run Smoke Test

Verify the container starts and the adapter connects successfully:

docker run --rm \
  -e GEMINI_API_KEY="$GEMINI_API_KEY" \
  -e WORKSPACE_ID="smoke-test" \
  molecule-gemini-cli:dev python -c "
import sys, os
from adapter import connect
try:
    connect(
        os.environ.get('ADAPTER_PLATFORM_URL', 'https://platform.molecule.ai'),
        os.environ['WORKSPACE_ID']
    )
    print('OK — adapter connected successfully')
    sys.exit(0)
except Exception as e:
    print(f'FAIL: {e}', file=sys.stderr)
    sys.exit(1)
"

Expected output:

OK — adapter connected successfully

If the exit code is non-zero, see Common Issues below.

Step 7: Verify Adapter Connects to Platform

Run a full agent round-trip test using the platform endpoint:

docker run --rm \
  -e GEMINI_API_KEY="$GEMINI_API_KEY" \
  -e WORKSPACE_ID="dev-local" \
  -e ADAPTER_PLATFORM_URL="https://platform.molecule.ai" \
  molecule-gemini-cli:dev python -c "
from adapter import connect, stream_response
connect('https://platform.molecule.ai', 'dev-local')
reply = stream_response('test-session', 'Say hello in one sentence.')
print(reply)
"

Expected output (or similar):

Hello! I'm ready to assist you.

If the connection is refused:

ConnectionRefusedError: [Errno 111] Connection refused

See issue adapter connection refused in the table below.

Common Issues

#	Issue	Symptom	Resolution
1	`GEMINI_API_KEY` is not set	Container starts but the agent produces no response; `stream_response()` hangs then times out with `AuthenticationError: Invalid API key` or silent hang	Confirm the env var is set: `echo $GEMINI_API_KEY`. If empty, obtain a key from https://aistudio.google.com/apikey and export it before `docker run`
2	Model not found	gemini-cli exits with `ValueError: Unknown model 'gemini-99-pro'. Did you mean 'gemini-2.0-flash'?`	Check `config.yaml` for the `runtime.model` value. Valid models: `gemini-2.0-flash`, `gemini-2.5-flash`, `gemini-2.5-pro`. Do not use preview or alias names
3	Docker networking	`ConnectionRefusedError` or `HTTPConnectError` when adapter tries to reach `platform.molecule.ai` inside the container	Ensure the host network is reachable from inside the container. Try `--network=host` on Linux, or map port explicitly: `-p 8080:8080`. Verify the platform URL is correct and the host machine is not behind a VPN blocking Docker's bridge network
4	Skill not loading	gemini-cli starts but reports `WARN: skill 'file-search' path /workspace/skills/file-search not found, skipping` for each skill	Verify skill directories exist in the image. Add them with a volume mount: `-v "$(pwd)/skills:/workspace/skills:ro"`. Ensure the skill paths in `config.yaml` match the mounted paths exactly
5	Adapter connection refused	`ConnectionRefusedError: [Errno 111] Connection refused` on `adapter.connect()` call	The adapter is trying to reach the platform at `ADAPTER_PLATFORM_URL` but nothing is listening there. If running against a local platform mock, start it first: `python -m local_platform_mock`. If running against the real platform, check that `ADAPTER_PLATFORM_URL` is set to the correct public endpoint and that the host machine can reach it

5.9 KiB Raw Blame History