Claude Code for Gitpod Cloud Dev — Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are developing in Gitpod, a cloud development environment that spins up ready-to-code workspaces from a .gitpod.yml configuration file. Gitpod launches a full VS Code or terminal environment in seconds with pre-installed dependencies, running services, and configured ports. Claude Code runs inside Gitpod workspaces, but it generates local machine configuration instead of Gitpod-specific setup.

What Claude Code Gets Wrong By Default

  1. Creates local setup scripts. Claude writes setup.sh scripts for local installation. Gitpod uses .gitpod.yml with init and command tasks that run automatically when a workspace starts — local setup scripts are ignored.

  2. Installs tools with apt/brew in terminal. Claude runs sudo apt install during development. Gitpod workspaces are ephemeral — install tools in .gitpod.Dockerfile or use Gitpod’s built-in tools. Apt installs vanish when the workspace restarts.

  3. Configures localhost for service access. Claude binds services to localhost:3000 and opens a browser tab to localhost. Gitpod exposes ports through unique URLs (*.gitpod.io) — configure the ports section in .gitpod.yml for proper access.

  4. Stores state in the filesystem. Claude saves files outside the /workspace directory. Only /workspace persists between workspace restarts — files in /home, /tmp, or other locations are lost.

The CLAUDE.md Configuration

# Gitpod Cloud Development

## Environment
- Platform: Gitpod (cloud dev environments)
- Config: .gitpod.yml at project root
- Dockerfile: .gitpod.Dockerfile for custom images
- Persistence: only /workspace directory persists

## Gitpod Rules
- Tools: install in .gitpod.Dockerfile, not apt/brew
- Tasks: init (runs once) and command (runs on restart)
- Ports: configure in .gitpod.yml ports section
- Env vars: Gitpod dashboard > Variables (encrypted)
- VS Code extensions: .gitpod.yml vscode.extensions
- Prebuilds: enabled via Gitpod dashboard for fast starts

## Conventions
- .gitpod.yml at project root
- init task: npm install, database setup
- command task: npm run dev (start dev server)
- ports: visibility public/private, onOpen behavior
- Use gp CLI for Gitpod-specific operations
- gp url 3000 to get the public URL for a port
- Store data in /workspace only

Workflow Example

You want to set up a Gitpod workspace for a React project with a PostgreSQL database. Prompt Claude Code:

“Create a Gitpod configuration for a React project with PostgreSQL. Set up the database in the init task, start the dev server in the command task, expose port 3000 publicly, and include the ESLint VS Code extension.”

Claude Code should create .gitpod.yml with an init task that starts PostgreSQL and runs migrations, a command task that runs npm run dev, a ports section exposing 3000 with onOpen: open-preview, and vscode.extensions including the ESLint extension ID.

Common Pitfalls

  1. Init task re-running on every restart. Claude puts npm install in the command task. Gitpod separates init (runs once, result cached in prebuild) from command (runs on every workspace start). Put slow setup in init and fast startup in command.

  2. Environment variables in .gitpod.yml. Claude puts API keys directly in the config file. Gitpod provides encrypted environment variables through the dashboard or gp env CLI — never commit secrets in .gitpod.yml.

  3. Docker Compose services not starting. Claude adds docker-compose.yml but the services do not start. Add docker-compose up -d in the init or before task, and ensure the Gitpod workspace has Docker support enabled in the image.