Same 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 development sandbox: one Docker container, bounded SDK workflows pointed at loopback endpoints, and explicit compatibility limits. Review the governing proprietary license and 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. This page gives them 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
Permitted personal checks should not ask for service-account keys, billing projects, or production credentials.
Not 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
These prompts come from the shared LocalCloud agent facts file and preserve the no-credentials, localhost-first boundary.
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. Verify Docker, start or reuse the localcloud container, 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 GCP.
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:24082, 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:24081, 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
Start the sandbox
Pull the canonical Docker image, start or reuse the localcloud container, and wait for the localhost health endpoint.
docker pull jaysen2apache/localcloud:latest
docker volume create localcloud-data
docker run -d --name localcloud \
-p 127.0.0.1:24080-24092:24080-24092 \
-m 4g \
-v localcloud-data:/var/lib/localcloud \
jaysen2apache/localcloud:latest02
Point SDKs at localhost
Export LocalCloud environment variables before running SDK, CLI, Terraform, or test commands.
eval "$(localcloud env)"03
Run the narrow check
Create the smallest dataset, topic, bucket, secret, queue, or table that proves the project path works locally.
curl -fsS http://localhost:24080/health04
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
27 available services plus 0 coming soon
Service metadata is generated from the shared catalog. Use service pages and compatibility docs for capability-specific claims.
3 supported locally 24 partial coverage 0 planned
| Service | Status | Endpoint | Boundary |
|---|---|---|---|
| Cloud Storage third-party-emulator | supported | STORAGE_EMULATOR_HOST=http://localhost:24081 | Local development coverage is partial. Known limits: [prod_only] IAM, lifecycle policies, and notifications not emulated in LocalCloud.. |
| Pub/Sub google-official | partial | PUBSUB_EMULATOR_HOST=localhost:24082 | Local development coverage is partial. Known limits: Schemas, snapshots, seek, dead-letter policy, filters, and other advanced subscription fields are not implemented on the configured endpoint., gcloud and console paths remain partial for advanced Pub/Sub workflows.. |
| Firestore google-official | partial | FIRESTORE_EMULATOR_HOST=localhost:24083 | Local development coverage is partial. Known limits: Seed and browser parity is not fully hardened., Index/query behavior is unverified.. |
| Bigtable custom-emulator | supported | BIGTABLE_EMULATOR_HOST=localhost:24084 | Local development coverage is partial. Known limits: [prod_only] Single-node emulator by design; clusters, multi-region, replication require Google infrastructure., GoogleSQL queries (ExecuteQuery/PrepareQuery) not supported — data-plane uses HBase-style API only., Change streams, app profiles, and logical views are not implemented in the emulator., Session protocol (OpenTable/OpenAuthorizedView/OpenMaterializedView) not implemented — not needed for correctness.. |
| Spanner extended-official | partial | SPANNER_EMULATOR_HOST=localhost:24085 | Local development coverage is partial. Known limits: Pinned extended Spanner emulator image; the exact image and immutable digest come from `SPANNER_EMULATOR_IMAGE` in the root Dockerfile., Change-stream support matrix — native gRPC/REST ExecuteStreamingSql supported; official SDK clients through SPANNER_EMULATOR_HOST supported; LocalCloud SQL Editor through managed run APIs or cancellable /query/stream NDJSON supported; gcloud spanner databases execute-sql unsupported for change streams because it uses unary ExecuteSql.. |
| BigQuery custom-emulator | partial | BIGQUERY_EMULATOR_HOST=http://localhost:24087 | Local development coverage is partial. Known limits: DuckDB type coercion is permissive where BigQuery is strict — queries accepted locally may error in production., Division by zero returns Inf/NaN instead of error; integer division returns int instead of FLOAT64., GROUP BY ROLLUP/CUBE/GROUPING SETS not supported., SEMI/ANTI JOIN syntax not supported (rely on EXISTS/NOT EXISTS transpile)., BQML (CREATE MODEL, ML.PREDICT, ML.EVALUATE, etc.) returns clear error., AEAD encryption functions and KLL quantile functions not implemented., GEOGRAPHY functions use haversine approximation, not true WGS84 geodesic., BIGNUMERIC truncated to DECIMAL(38,9); FARM_FINGERPRINT requires pyfarmhash for correct values., Time travel (FOR SYSTEM_TIME AS OF), continuous queries, graph queries, search/vector indexes not supported., External object tables (OBJ.* functions) not supported.. |
| Google Sheets local-facade | partial | SHEETS_EMULATOR_HOST=http://localhost:24080 | Local development coverage is partial. Known limits: Spreadsheet metadata, writes, formulas, range evaluation, OAuth, and production Sheets access are not emulated., Values are selected by exact stored A1 range and project scope.. |
| Secret Manager local-facade | partial | SECRET_MANAGER_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: [prod_only] Rotation and CMEK (customer-managed encryption keys)., Per-secret IAM is not complete.. |
| Cloud Tasks local-facade | partial | CLOUD_TASKS_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: App Engine tasks and OAuth token generation are not complete.. |
| Cloud Scheduler local-facade | partial | CLOUD_SCHEDULER_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: Timezone rules beyond cron-utils support are not fully verified.. |
| Cloud Functions (2nd Gen) local-facade | partial | CLOUD_FUNCTIONS_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: Build and container execution are metadata-only; use Functions Framework locally.. |
| AlloyDB local-facade | partial | ALLOYDB_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: [prod_only] PSC (Private Service Connect) and cross-region replication., Backup/restore is not complete.. |
| Dataproc local-facade | partial | DATAPROC_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: Autoscaling and Kubernetes cluster mode are not complete., Runtime execution requires Docker socket access; without it, cluster metadata remains available but Spark/Hadoop processes are not started.. |
| Cloud IAM local-facade | partial | IAM_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: Role validation, conditions, and deny policies are not complete.. |
| Cloud Resource Manager local-facade | supported | CLOUD_RESOURCE_MANAGER_EMULATOR_HOST=http://localhost:24080 | Local development coverage is partial. Known limits: [prod_only] Organization/folder hierarchy not modeled in LocalCloud.. |
| Service Usage local-facade | partial | SERVICE_USAGE_EMULATOR_HOST=http://localhost:24080 | Local development coverage is partial. Known limits: Quotas and service entitlement behavior are stubs.. |
| Cloud Billing local-facade | partial | CLOUD_BILLING_EMULATOR_HOST=http://localhost:24080 | Local development coverage is partial. Known limits: Real billing, budget enforcement, and cost export are not implemented.. |
| Cloud Logging local-facade | partial | CLOUD_LOGGING_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: Metrics, exclusions, audit logs, and production sink behavior are limited.. |
| Cloud Monitoring local-facade | partial | CLOUD_MONITORING_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: Alerting, uptime checks, and dashboards are partial.. |
| GKE local-facade | partial | GKE_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: Kubernetes runtime parity depends on host runtime/k3d integration., [prod_only] Node pools, autoscaling, and upgrades (GCP-managed cluster autoscaler, regional instance groups).. |
| Compute Engine local-facade | partial | COMPUTE_EMULATOR_HOST=http://localhost:24080 | Local development coverage is partial. Known limits: [prod_only] Persistent disks and live migration (hypervisor-level storage/VM management)., Snapshots, instance templates, and VPC networking are not yet emulated.. |
| Cloud Run local-facade | partial | CLOUD_RUN_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: Container execution and routing require host runtime architecture., [prod_only] Custom domains and production routing (Google Front End load balancers, managed TLS).. |
| Memorystore (Redis/Valkey) third-party-emulator | partial | REDIS_HOST=localhost:24089 | Local development coverage is partial. Known limits: Pub/Sub, Lua, streams, and MULTI/EXEC are not supported.. |
| Cloud Workflows local-facade | partial | WORKFLOWS_EMULATOR_HOST=localhost:24080 | Local development coverage is partial. Known limits: In-flight execution checkpointing is not durable across restart.. |
| Vertex AI local-facade | partial | AIPLATFORM_EMULATOR_HOST=http://localhost:24080 | Local development coverage is partial. Known limits: [prod_only] Model training and tuning (requires TPU/GPU clusters)., Prediction endpoints and model management are out of current scope.. |
| Cloud KMS local-facade | partial | CLOUD_KMS_EMULATOR_HOST=http://localhost:24080 | Local development coverage is partial. Known limits: [prod_only] HSM (physical FIPS 140-2 Level 3 hardware) and EKM (external key manager providers)., Import jobs and Cloud HSM level enforcement are not implemented.. |
| Cloud SQL local-facade | partial | CLOUD_SQL_EMULATOR_HOST=http://localhost:24080 | Local development coverage is partial. Known limits: [prod_only] Read replicas (cross-region replication) and PSC (Private Service Connect)., MySQL instances share one on-demand MySQL 8.4.11 server; schemas and physical wire logins are deterministically isolated by project and instance., Backup/restore execution is not implemented.. |
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.
States that LocalCloud is limited to uses permitted by the governing proprietary license and is not a production GCP replacement.
Keeps bounded local workflows on loopback endpoints and stops rather than requesting or falling back to real Google Cloud credentials.
Uses the reviewed image repository jaysen2apache/localcloud:latest; the mutable tag remains release-unverified, so prefer localcloud start and pin a qualified digest for release workflows.
Points SDKs and Terraform to localhost/emulator endpoints before any verification step.
Warns agents to stop rather than falling back to real GCP when Docker or LocalCloud is unavailable.
Links service-specific claims to the service catalog, compatibility docs, or reviewed evidence.
Instructs production validation against real Google Cloud after unsetting emulator environment variables.
/ai/agents.md
A hosted Markdown execution guide for agents. It includes startup commands, endpoints, service matrix, copy prompts, and safety rules.
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 routes give agents compact service, compatibility, and docs context sourced from shared LocalCloud metadata.
Open Markdown indexagent-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.
Web console
http://localhost:24080 Inspect service health, local data, logs, and administrative state.
Health check
http://localhost:24080/health Wait for LocalCloud readiness before SDK, Terraform, seed, or other local workflows.
Shell environment export
http://localhost:24080/env?format=shell Set emulator endpoint variables for local SDK and CLI workflows.
Terraform environment export
http://localhost:24080/env?format=terraform Set endpoint overrides for local Terraform validation without real GCP credentials.