LocalSame SDKs, localhost endpoints
Agents should keep project code pointed at standard Google Cloud SDKs while exporting emulator host variables for local runs.
Agent-safe local GCP
Give coding agents a local Google Cloud target
LocalCloud is a local Google Cloud emulator: one Docker container that answers Google Cloud SDK calls on localhost, so code and tests run without a GCP account, credentials, or billing. Validate against real Google Cloud before production. Agents can run SDKs, Terraform, seed data, and integration checks against localhost instead of reaching for production Google Cloud.
Human explanation
Why agents need this page
AI agents often discover code paths that expect Google Cloud. A repository that uses BigQuery, Pub/Sub, Cloud Storage, Spanner, Bigtable, or Terraform usually expects a real project, so an agent that follows that path blindly turns a local test into a credential request, a billing event, or a change to shared infrastructure. This page gives agents a safe default: start LocalCloud, route SDKs to localhost, prove behavior locally, and stop rather than silently using real cloud credentials.
No GCP account by default
Agents shouldn't ask for service-account keys, billing projects, or production credentials for local checks.
Not a production replacement
LocalCloud helps verify local behavior. Release readiness still requires testing against real Google Cloud after emulator variables are removed.
Copy prompts
Prompt an agent with a safe LocalCloud task
Each prompt keeps the agent on localhost with no credentials.
Give an agent one URL and have it start the local GCP sandbox.
Start LocalCloud
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.
Have an agent wire an existing project to LocalCloud safely.
Configure this repo
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.
Have an agent add a permitted non-production LocalCloud CI workflow.
Configure internal CI
Read https://local.cloud/docs/licensing/ before changing this automation. Keep the workflow within the Public Preview License's non-production boundary. Propose the smallest change that starts LocalCloud, waits for readiness, exports emulator env vars, runs integration tests locally, and avoids real GCP secrets.
Diagnose why SDKs or Terraform are still reaching real Google Cloud.
Troubleshoot routing
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.
Ask an agent to validate BigQuery code against the local emulator.
BigQuery local test
Use LocalCloud to test BigQuery code locally. Read https://local.cloud/ai/agents.md and the BigQuery docs, set BIGQUERY_EMULATOR_HOST for localhost, create a local dataset/table, insert sample rows, run a representative query, and call out any unsupported SQL features instead of using real BigQuery.
Ask an agent to validate Pub/Sub event code locally.
Pub/Sub local test
Use LocalCloud to test Pub/Sub locally. Read https://local.cloud/ai/agents.md, set PUBSUB_EMULATOR_HOST=localhost:5383, create a topic and subscription, publish one test message, pull or stream it, ack it, and verify the payload without using real GCP credentials.
Ask an agent to validate bucket/object code locally.
Cloud Storage local test
Use LocalCloud to test Cloud Storage locally. Read https://local.cloud/ai/agents.md, set STORAGE_EMULATOR_HOST=http://localhost:5382, create a bucket, upload a small object, list it, download it, and verify content without using real GCP credentials.
Workflow
Agent execution loop
Keep the loop small: local runtime, localhost environment, narrow service proof, explicit production validation later.
01
Install and start
Install the CLI (or run brew install LocalGCloud/tap/localcloud), check Docker, and start LocalCloud on localhost-only ports.
curl -fsSL https://local.cloud/install.sh | sh
localcloud doctor
localcloud start --local-only02
Confirm readiness
Wait for the runtime readiness endpoint before any SDK, CLI, Terraform, or test command.
curl -fsS http://localhost:5380/readiness03
Point SDKs at localhost
Export the LocalCloud environment, then run the project’s smallest SDK test to prove its service path works.
eval "$(localcloud env)"04
Keep production separate
Do not treat emulator success as production proof. Unset emulator variables and validate against real GCP before release.
unset STORAGE_EMULATOR_HOST PUBSUB_EMULATOR_HOST FIRESTORE_EMULATOR_HOST BIGQUERY_EMULATOR_HOST Service matrix
25 local services
Use service pages and compatibility docs for capability-specific claims.
25 supported locally 2 unsupported
| Service | Endpoint | Boundary |
|---|---|---|
| Firestore google-official | FIRESTORE_EMULATOR_HOST=localhost:5384 | Opt-in to save memory: add firestore to localcloud start --services, which sets the exact list of services to run. |
| Bigtable custom-emulator | BIGTABLE_EMULATOR_HOST=localhost:5385 | Documented local workflows with these boundaries: Sink preserves cells past later filters; invalid inside a Condition; Verify backup listing and project deletion through the native admin API. |
| Spanner extended-official | SPANNER_EMULATOR_HOST=localhost:5386 | Documented local workflows with these boundaries: Change streams require streaming SQL; Backups and durable stream recovery require a persistent data directory. |
| AlloyDB local-facade | ALLOYDB_EMULATOR_HOST=localhost:5380 | Documented local workflows with these boundaries: Backup restore covers metadata; No advanced AlloyDB engine behavior or replicas. |
| Memorystore (Redis/Valkey) third-party-emulator | REDIS_HOST=localhost:5390 | Documented local workflows with these boundaries: Shared server; database numbers do not isolate Pub/Sub channels; No multi-shard topology, managed failover, or project authorization. |
| Cloud SQL local-facade | CLOUD_SQL_EMULATOR_HOST=http://localhost:5380 | Documented local workflows with these boundaries: Shared installed engines; version labels do not provision separate versions; No per-instance database flags; infrastructure settings are metadata. |
| Pub/Sub local-facade | PUBSUB_EMULATOR_HOST=localhost:5383 | Documented local workflows with these boundaries: No exactly-once delivery, exports, transforms, or push payload wrappers; Push receivers must trust LocalCloud's issuer and JWKS; validate delivery with your application. |
| Cloud Tasks local-facade | CLOUD_TASKS_EMULATOR_HOST=localhost:5380 | Documented local workflows with these boundaries: No App Engine delivery or routing/header overrides; Authenticated receivers must trust LocalCloud's issuer and JWKS. |
| Cloud Scheduler local-facade | CLOUD_SCHEDULER_EMULATOR_HOST=localhost:5380 | Documented local workflows with these boundaries: No App Engine targets; authenticated receivers must trust the local issuer and JWKS; No interrupted-attempt replay or downtime backfill. |
| Cloud Workflows local-facade | WORKFLOWS_EMULATOR_HOST=localhost:5380 | Documented local workflows with these boundaries: Limited connector and expression support; Active executions fail on restart with InstanceRestart. |
| Cloud Functions (2nd Gen) local-facade | CLOUD_FUNCTIONS_EMULATOR_HOST=localhost:5380 | Documented local workflows with these boundaries: Requires your own execution target; No source builds or managed function containers. |
| GKE local-facade | GKE_EMULATOR_HOST=localhost:5380 | Opt-in to save memory: add gke to localcloud start --services, which sets the exact list of services to run. |
| Compute Engine Unsupported local-facade | No local endpoint | Not available locally. Use Google Cloud for this service. |
| Cloud Run local-facade | CLOUD_RUN_EMULATOR_HOST=localhost:5380 | Opt-in to save memory: add cloudrun to localcloud start --services, which sets the exact list of services to run. |
| Vertex AI Unsupported local-facade | No local endpoint | Not available locally. Use Google Cloud for this service. |
| Secret Manager local-facade | SECRET_MANAGER_EMULATOR_HOST=localhost:5380 | Documented local workflows with these boundaries: No automatic rotation notifications or topic delivery; Authorization varies by transport and IAM mode. |
| Cloud IAM local-facade | IAM_EMULATOR_HOST=localhost:5380 | Documented local workflows with these boundaries: Enforcement varies by service, transport, and IAM mode; Open/permissive probes do not establish enforced access. |
| Cloud KMS local-facade | CLOUD_KMS_EMULATOR_HOST=localhost:5380 | Documented local workflows with these boundaries: SOFTWARE keys; hardware custody and Google authority are cloud-only; Inventory/Autokey: project-owned global Secret Manager resources only. |
| Cloud Resource Manager local-facade | CLOUD_RESOURCE_MANAGER_EMULATOR_HOST=http://localhost:5380 | Documented local workflows with these boundaries: No organization/folder lifecycle, moves, search, or full ancestry; No project auto-registration on direct emulator listeners. |
| Service Usage local-facade | SERVICE_USAGE_EMULATOR_HOST=http://localhost:5380 | Documented local workflows with these boundaries: Reports ENABLED; runtime activation uses LocalCloud service controls; No quota enforcement, billing, or project-specific entitlement. |
| Cloud Billing local-facade | CLOUD_BILLING_EMULATOR_HOST=http://localhost:5380 | Documented local workflows with these boundaries: No cost accumulation or threshold notifications; No billing exports or budget-triggered automation. |
| Cloud Logging local-facade | CLOUD_LOGGING_EMULATOR_HOST=localhost:5380 | Documented local workflows with these boundaries: Limited Google filter semantics; Metric definitions do not derive values from log entries. |
| Cloud Monitoring local-facade | CLOUD_MONITORING_EMULATOR_HOST=localhost:5380 | Documented local workflows with these boundaries: Limited query alignment/aggregation; Validate alert evaluation, notifications, uptime execution, and dashboards in Google Cloud. |
| Cloud Storage third-party-emulator | STORAGE_EMULATOR_HOST=http://localhost:5382 | Documented local workflows with these boundaries: No bucket versioning, archive events, or managed folders; No lifecycle scheduling or retention enforcement. |
| BigQuery custom-emulator | BIGQUERY_EMULATOR_HOST=http://localhost:5388 | Documented local workflows with these boundaries: Function/input-specific SQL limits; check the feature matrix; No ingestion-time partitioning or nested policy tags. |
| Dataproc local-facade | DATAPROC_EMULATOR_HOST=localhost:5380 | Documented local workflows with these boundaries: Requires Docker daemon access; Cloud scaling, automated node repair, and production SLAs are cloud-only. |
| Google Sheets local-facade | SHEETS_EMULATOR_HOST=http://localhost:5380 | Documented local workflows with these boundaries: Read-only auxiliary fixture API; No spreadsheet metadata, writes, range slicing, or formulas. |
Safety boundaries
What agents must not do
LocalCloud removes cloud dependencies from local development; it does not remove the responsibility to validate production behavior with real Google Cloud.
Use only local endpoint values. If a step would need real Google Cloud or real credentials, stop and report it.
Never ask for or use service-account keys, application default credentials, production project IDs, or billing accounts.
Export the LocalCloud environment in the same shell or test runner before any SDK, CLI, or Terraform step.
If Docker or LocalCloud is unavailable, stop and report the blocker instead of falling back to real Google Cloud.
Prefer the LocalCloud CLI. The `latest` image tag is mutable, so pin an image digest when repeatability matters.
Back service-specific claims with the service page or https://local.cloud/compatibility/.
Use LocalCloud only for the non-production work the Public Preview License permits.
Before production, unset the emulator variables and validate the change against real Google Cloud.
/ai/agents.md
A hosted Markdown guide for agents: install-first quick start, rules, workflow, and endpoints.
Open Markdown guideAGENTS.md template
AGENTS.md belongs inside a repository and tells coding agents how to behave in that codebase. Copy this template into a repo when you want LocalCloud to be the default safe GCP target.
Raw resource index
HTML pages stay canonical for humans; raw Markdown pages give agents compact service, compatibility, and docs context.
- /ai/services.md: service matrix and endpoint variables
- /ai/compatibility.md: what each service runs locally
- /ai/docs.md: SDK, Terraform, seed data, and console docs
agent-skills/
Reusable LocalCloud Agent Skills cover BigQuery, Pub/Sub, Terraform, internal automation, seed data, and SDK tests. Copy them into .agents/skills/ for a permitted non-production project.
Agent endpoints
URLs agents can rely on
Use these localhost endpoints after LocalCloud is running, and use the public docs for service-specific context. MCP clients connect to the runtime's /mcp endpoint, or through the localcloud mcp stdio bridge when they can't use Streamable HTTP; see LocalCloud MCP integration.
Web console
http://localhost:5380 Inspect service health, local data, logs, and administrative state.
Health check
http://localhost:5380/health Inspect runtime health; use the readiness endpoint before application traffic.
Readiness check
http://localhost:5380/readiness Wait for configured services to be ready, then verify the exact SDK/API workflow.
Shell environment export
http://localhost:5380/env?format=shell Set emulator endpoint variables for local SDK and CLI workflows.
Terraform environment export
http://localhost:5380/env?format=terraform Set endpoint overrides for local Terraform validation without real Google Cloud credentials.