# GCP Workstations

> Use when provisioning, configuring, or operating Google Cloud Workstations as a single-developer AI/dev environment with Claude Code, Antigravity CLI (agy), GitHub Copilot CLI, and supporting tooling. Covers cluster/config/workstation lifecycle, custom images, persistent home semantics, per-tool authentication strategies, networking, cost optimization, and security gotchas.

- Skill: `joogy06/gcp-workstations` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add joogy06/gcp-workstations`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joogy06/gcp-workstations/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: joogy06 (https://skillmd.com/u/joogy06)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/joogy06/gcp-workstations

---


# GCP Workstations for AI Dev

Single-developer Google Cloud Workstations playbook. Provisions a workstation that runs Claude Code 2.1, Antigravity CLI (agy) 1.0, GitHub Copilot CLI 1.0, and supporting tooling, with sensible auth and cost defaults.

This is **not** a multi-tenant guide. Single-dev assumptions apply throughout.

## When to use

- Spinning up a new GCP Workstation for AI-assisted development
- Authoring or updating the custom image with the AI CLI stack
- Picking the right auth flow per tool on a cloud VM
- Estimating monthly cost (or comparing against alternatives)
- Diagnosing persistence, networking, or credential-store issues

## Versions and assumptions

| Component | Version targeted |
|---|---|
| Google Cloud Workstations | API v1 (April 2026) |
| Base image | `us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest` |
| Node.js | 22 LTS (for the AI CLIs) |
| Claude Code | 2.1.x via `@anthropic-ai/claude-code` |
| Antigravity CLI (agy) | 1.0.4 (`agy` binary at `~/.local/bin/agy`). TODO(agy): confirm agy install + auth on GCP Workstation |
| GitHub Copilot CLI | 1.0.x via `@github/copilot` |

## Quick task index

| Task | Read |
|---|---|
| Provision a new cluster/config/workstation | `references/provision.md` |
| Build the custom Dockerfile (AI CLIs preinstalled) | `references/custom-image.md` + `scripts/Dockerfile.ai-dev` |
| Push image to Artifact Registry | `references/custom-image.md` (Push section) |
| Pick auth per tool (Claude / agy / Copilot) | `references/auth-per-tool.md` |
| Understand `$HOME` vs `/var`/`/tmp` persistence | `references/persistent-home.md` |
| Manage secrets (Secret Manager + use-time fetch) | `references/secrets-and-security.md` |
| Configure networking (public/private, IAP, egress) | `references/networking.md` |
| Estimate cost and pick the right tier | `references/cost-optimization.md` |
| Common gotchas (libsecret, clock drift, OAuth) | `references/gotchas-and-fixes.md` |
| Run the lifecycle from end to end | `scripts/create-workstation.sh` |
| Workstation startup hook with use-time secret fetch | `assets/startup-script.sh` |

## Lifecycle in three commands

```bash
# 1. Cluster (one per project, region)
gcloud workstations clusters create my-cluster \
  --region=us-central1 \
  --network=projects/$PROJECT/global/networks/default \
  --subnetwork=projects/$PROJECT/regions/us-central1/subnetworks/default

# 2. Config (one per machine type / image / persistent disk shape)
gcloud workstations configs create ai-dev-config \
  --cluster=my-cluster \
  --region=us-central1 \
  --machine-type=e2-standard-4 \
  --container-custom-image=us-central1-docker.pkg.dev/$PROJECT/ai-dev/ai-dev:latest \
  --pd-disk-type=pd-ssd \
  --pd-disk-size=200 \
  --idle-timeout=1800s \
  --running-timeout=43200s

# 3. Workstation
gcloud workstations create my-station \
  --cluster=my-cluster \
  --config=ai-dev-config \
  --region=us-central1
```

`scripts/create-workstation.sh` runs this end-to-end with idempotency and error handling.

## Persistence summary

| Path | Persists across stop/start? | Persists across delete-workstation? |
|---|---|---|
| `$HOME` (e.g. `/home/user`) | YES | YES (the persistent disk is decoupled from the workstation lifecycle) |
| `/var`, `/tmp`, `/etc`, `/usr` | NO | NO |
| Hidden caches outside `$HOME` (e.g. `/root/.cache`) | NO | NO |

This means:

- `~/.claude/`, `~/.antigravity/`, `~/.gemini/` (agy config lives under `~/.antigravity/` and `~/.gemini/antigravity-cli/`), `~/.copilot/`, `~/.config/gh/`, `~/.npm/`, `~/.cargo/`, `~/.npm-global/` all persist
- Anything you `apt install` is gone after restart unless it's baked into the image
- Build a custom image (`scripts/Dockerfile.ai-dev`) for everything that should survive

## Auth per tool — one-line summary

| Tool | Recommended on GCP Workstation | Why |
|---|---|---|
| Claude Code | Vertex AI ADC (`CLAUDE_CODE_USE_VERTEX=1`) | Metadata server provides ADC; no key file; same region as Vertex |
| Antigravity CLI (agy) | Antigravity account login | agy authenticates via its own Antigravity account (config under `~/.antigravity/`), NOT Vertex ADC. TODO(agy): confirm agy install + auth on GCP Workstation |
| GitHub Copilot CLI | Device flow with TCP tunnel fallback | OAuth opens a browser; use `gcloud workstations start-tcp-tunnel` to forward localhost to your laptop |
| Codex CLI | OpenAI account login | No GCP integration; works on cloud VM with copy-paste device code |

See `references/auth-per-tool.md` for the full table and exact commands.

## Cost realistic numbers

- ~$144/mo fixed cluster fee (you pay this even with no workstations running, per cluster)
- ~$30/mo compute for an `e2-standard-4` running ~6 h/day on a 1800s idle timeout
- ~$20/mo for the 200 GB pd-ssd persistent disk
- **Total realistic for daily-use single dev: $170-280/mo**

Cheaper alternative: a non-spot GCE VM with a manually built custom image. ~50% cheaper but no managed image lifecycle, no built-in IDE-in-browser, no auto-stop.

**Spot VMs are NOT recommended** for persistent dev — interruptions kill long-running operations and `$HOME` is on a separate disk regardless.

See `references/cost-optimization.md` for detail.

## Anti-patterns

| Don't | Why |
|---|---|
| Run `apt install` and expect it to persist | `/usr` does not survive restart. Bake into the custom image. |
| Export secrets via `/etc/profile.d/` | Plaintext on disk + visible to all users. Use Secret Manager + use-time fetch. See `references/secrets-and-security.md`. |
| Use spot VMs for persistent dev | Interruptions kill in-flight operations. Use regular workstations. |
| Skip `libsecret-1-0` in the Dockerfile | Without it, CLI credential stores fail and tokens go to plaintext fallbacks |
| Skip `chrony` in the Dockerfile | Clock drift causes OAuth 401s and TLS handshake failures |
| Forget the `--network` flag on cluster creation | Default cluster has no inbound; you'll need to recreate. |
| Mix multiple users on one workstation | Single-dev assumption holds throughout this skill. Multi-user is out of scope. |
| Use the legacy `code-oss` image without updating | Pin to `:latest` is fine for personal dev; lock to a digest for reproducibility. |
| Run `gcloud auth login` on the workstation expecting browser to open on your laptop | The browser opens on the VM (no display). Use `gcloud auth application-default login --no-launch-browser` and copy the URL. |
| Embed the SA key file in the image | Key files in images are an audit nightmare. Use ADC via metadata server. |

## See also

- `references/provision.md` — exact gcloud commands
- `references/custom-image.md` — Dockerfile, build, push
- `references/auth-per-tool.md` — canonical auth recommendation
- `references/persistent-home.md` — what survives restarts
- `references/secrets-and-security.md` — Secret Manager pattern, anti-patterns
- `references/networking.md` — public/private, IAP, egress allow list
- `references/cost-optimization.md` — pricing breakdown, alternatives
- `references/gotchas-and-fixes.md` — libsecret, clock drift, browser OAuth, marketplace
- `scripts/Dockerfile.ai-dev` — the actual Dockerfile (ready to `docker build`)
- `scripts/create-workstation.sh` — idempotent lifecycle script
- `assets/startup-script.sh` — workstation startup template with use-time secret fetch
- `claude-code-cli`, `antigravity-cli`, `gh-copilot-cli` — per-tool docs
- `docker-fundamentals`, `docker-security` — for Dockerfile review and hardening
- `ubuntu-server-admin` — for OS-level tuning if you switch from code-oss to a base image