LocalCloud Claude Code GCP Sandbox with LocalCloud
Get started
local.cloud / agents
Read this page as Markdown ↗
local.cloud — Claude Code GCP Sandbox with LocalCloud .md Open tab
LocalCloud Google Cloud in-a-box
Claude Code sandbox

Claude Code local GCP sandbox

Claude Code is strongest when it can inspect a repository, run shell commands, and verify the narrowest failing path. LocalCloud gives that terminal workflow a local GCP surface: one Docker container, standard SDKs pointed at localhost, and no default GCP account or billing project.

Read docs Check compatibility SDK examples
Fact

Terminal-first setup using Docker and localhost endpoints.

Fact

Docker image: agentcloud/localcloud:latest.

Fact

Best for repo-aware SDK tests, Terraform checks, and troubleshooting loops.

Claude-specific workflow

Start from the repo, not from a blank prompt

Ask Claude Code to read the project, identify the Google Cloud SDKs and services in use, then fetch /ai/agents.md before it changes code. That sequence keeps LocalCloud as the runtime target instead of a generic cloud migration suggestion.

  • Have Claude verify Docker and reuse an existing localcloud container when present.
  • Export emulator variables into the exact shell or test runner it will use.
  • Run one representative SDK operation before editing broader test suites.
Human approval boundary

Approve shell actions, but do not provide cloud secrets

Claude Code may request permission before running Docker or test commands. The safe path is to approve local Docker, curl, and localhost SDK checks while refusing requests for service-account keys, ADC setup, or production project IDs.

Copy-ready setup

Commands and prompts

Copy a prompt for your coding agent

Start LocalCloud

Give an agent one URL and have it start the local GCP sandbox.

Fetch https://local.cloud/ai/agents.md and follow the instructions to start LocalCloud on my machine. Install the LocalCloud CLI if it is missing, verify Docker, start or reuse LocalCloud, export emulator environment variables, and run one local GCP SDK/API smoke check. Do not ask for or use real GCP credentials.

Configure this repo

Have an agent wire an existing project to LocalCloud safely.

Set up this repository to use LocalCloud for local GCP development. First read https://local.cloud/ai/agents.md, then inspect this repo, identify the GCP services and SDK language, configure emulator environment variables, and run the narrowest integration test against localhost. Do not use real GCP credentials or production endpoints.

Troubleshoot routing

Diagnose why SDKs or Terraform are still reaching real Google Cloud.

Troubleshoot my LocalCloud setup. Read https://local.cloud/ai/agents.md, check whether Docker and the localcloud container are healthy, verify emulator environment variables are set in this shell/test runner, and identify any SDK or Terraform configuration that could still call real Google Cloud.
Claude Code bootstrap 
Read https://local.cloud/ai/agents.md, inspect this repository for Google Cloud SDK usage, start or reuse LocalCloud with Docker, export emulator env vars into this shell, and run the smallest local SDK smoke test. Do not ask for GCP credentials.
Claude Code smoke-test report 
Claude, use LocalCloud to run a local GCP smoke test for this repository. Do not request GCP credentials. Show the LocalCloud health check, active emulator env vars, and one SDK operation against localhost.
LocalCloud commands 
curl -fsSL https://local.cloud/install.sh | sh
localcloud doctor
localcloud start --local-only
curl -fsS http://localhost:5380/readiness
eval "$(localcloud env)"
localcloud console
Docker-only fallback 
docker volume create localcloud-data

docker run -d --name localcloud \
  -p 127.0.0.1:5380-5405:5380-5405 \
  -m 4g \
  -v localcloud-data:/var/lib/localcloud \
  agentcloud/localcloud:latest

for attempt in $(seq 1 60); do curl -fsS http://localhost:5380/readiness && break; sleep 2; done
eval "$(curl -fsS 'http://localhost:5380/env?format=shell')"
Production boundary

Before production

Use LocalCloud for non-production development, testing, and CI under the Public Preview License, check each service's local boundaries, and validate against real Google Cloud before you deploy.

  • Claude Code is not a hosted isolation boundary by itself; LocalCloud isolates Google Cloud side effects, not arbitrary shell commands.
  • If a test needs IAM, quota, latency, managed networking, or production-specific behavior, keep a real Google Cloud validation step.
Related

Next steps

  • SDK examples — Use standard Google Cloud SDKs pointed at localhost.
  • Seed data — Load deterministic fixtures for repeatable agent and CI runs.
Desktop view