Same SDKs, localhost endpoints
Agents should keep project code pointed at standard Google Cloud SDKs while exporting emulator host variables for local runs.
localcloud is cloud for agents: a local Google Cloud runtime for AI coding agents, developers and CI pipelines. Build and test with 25 Google Cloud services on localhost in one Docker container, with no GCP account, credentials or billing. Free during the public preview. 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.
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.
Agents should keep project code pointed at standard Google Cloud SDKs while exporting emulator host variables for local runs.
Agents shouldn't ask for service-account keys, billing projects, or production credentials for local checks.
LocalCloud helps verify local behavior. Release readiness still requires testing against real Google Cloud after emulator variables are removed.
Each prompt keeps the agent on localhost with no credentials.
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.
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.
Read https://local.cloud/docs/licensing/ first. Then propose the smallest change that starts LocalCloud, waits for readiness, exports emulator env vars and runs integration tests locally, with no real GCP secrets.
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.
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.
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.
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.
Keep the loop small: local runtime, localhost environment, narrow service proof, explicit production validation later.
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-only Wait for the runtime readiness endpoint before any SDK, CLI, Terraform, or test command.
curl -fsS http://localhost:5380/readiness Export the LocalCloud environment, then run the project’s smallest SDK test to prove its service path works.
eval "$(localcloud env)" 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 Use service pages and compatibility docs for capability-specific claims.
| Service | Endpoint | Boundary |
|---|---|---|
| Firestore | FIRESTORE_EMULATOR_HOST=localhost:5384 | Opt-in: start with localcloud start --services firestore (plus any other services you need). |
| Bigtable | BIGTABLE_EMULATOR_HOST=localhost:5385 | Limits: IAM policies are stored and returned but not enforced; change streams use a single partition. Raster statistics (ST_REGIONSTATS) and legacy table snapshots: use Google Cloud; Sink bypasses later filters and is invalid inside Condition. Multi-column materialized-view keys use a local encoding; read them back with the native client. |
| Spanner | SPANNER_EMULATOR_HOST=localhost:5386 | Limits: Change streams use streaming SQL; Backups and change-stream history persist in the LocalCloud volume; project checkpoints do not capture Spanner. |
| AlloyDB | ALLOYDB_EMULATOR_HOST=localhost:5380 | Limits: Restore creates an empty cluster and backups hold no data. Engine flags, read pools, and replicas: use Google Cloud; AlloyDB connectors and the Auth Proxy aren't supported; connect directly to the local PostgreSQL port. |
| Memorystore (Redis/Valkey) | REDIS_HOST=localhost:5390 | Limits: One shared server: database numbers don't isolate Pub/Sub channels, and AUTH and server configuration aren't enforced; About 16 instance create and delete cycles per data volume; deleted databases aren't reused. |
| Cloud SQL | CLOUD_SQL_EMULATOR_HOST=http://localhost:5380 | Limits: Instances share local engines. Version labels, database flags, tiers, and network settings don't create separate servers or change engine settings; Backups are metadata. Export, import, restore, and replica calls return DONE without moving data; validate restore and migration results in Google Cloud. |
| Pub/Sub | PUBSUB_EMULATOR_HOST=localhost:5383 | Limits: Design consumers for at-least-once redelivery. Exactly-once delivery, per-key ordered delivery, export subscriptions, and message transforms: validate in Google Cloud; Messages don't expire by age unless enforce_subscription_retention is on, and a retained backlog is held in memory; purge test subscriptions or turn retention on. |
| Cloud Tasks | CLOUD_TASKS_EMULATOR_HOST=localhost:5380 | Limits: App Engine dispatch, logging sampling, CMEK, and pull queues: use Google Cloud; Authenticated receivers verify tokens against the local issuer and JWKS. A removed task ID stays reserved for one hour. |
| Cloud Scheduler | CLOUD_SCHEDULER_EMULATOR_HOST=localhost:5380 | Limits: Authenticated receivers verify tokens against the local issuer and JWKS. App Engine targets: use Google Cloud; Interrupted attempts aren't replayed, and a job that came due while LocalCloud was stopped runs once without backfilling the rest; validate catch-up behavior in Google Cloud. |
| Cloud Workflows | WORKFLOWS_EMULATOR_HOST=localhost:5380 | Limits: Connector and expression coverage is limited; validate other connectors in Google Cloud; Conditions must be booleans: a number, string, or missing field raises TypeError. |
| Cloud Functions (2nd Gen) | CLOUD_FUNCTIONS_EMULATOR_HOST=localhost:5380 | Limits: Bring your own HTTP handler; LocalCloud routes requests to it; HTTP, Pub/Sub, and Firestore document triggers run locally, and Firestore events arrive as JSON CloudEvents. Storage and Audit Log Eventarc triggers, protobuf event payloads, and Google identity tokens: validate in Google Cloud. |
| GKE | GKE_EMULATOR_HOST=localhost:5380 | Opt-in: start with localcloud start --services gke (plus any other services you need). |
| Compute Engine Unsupported | No local endpoint | Not available locally. Use Google Cloud for this service. |
| Cloud Run | CLOUD_RUN_EMULATOR_HOST=localhost:5380 | Opt-in: start with localcloud start --services cloudrun (plus any other services you need). |
| Vertex AI Unsupported | No local endpoint | Not available locally. Use Google Cloud for this service. |
| Secret Manager | SECRET_MANAGER_EMULATOR_HOST=localhost:5380 | Limits: Automatic rotation notifications and topic delivery: validate in Google Cloud; Per-secret IAM policies are stored but secret reads are not checked against them; validate data-access policies in Google Cloud. |
| Cloud IAM | IAM_EMULATOR_HOST=localhost:5380 | Limits: Strict mode checks stored policies for IAM, KMS, Cloud Storage, Cloud Tasks, and Workflows; other services follow the strict-mode policy file. Open mode is not access control; Supported conditions and project inheritance work locally. Full CEL, organization and folder ancestry, and deny policies: validate in Google Cloud. |
| Cloud KMS | CLOUD_KMS_EMULATOR_HOST=localhost:5380 | Limits: Software-protected keys run locally; HSM and external key versions are refused. EKM connection settings are stored and checked locally. Hardware key custody and Google authority: use Google Cloud; Automatic rotation and the end of a scheduled destruction do not run locally; create versions and set the primary yourself. |
| Cloud Resource Manager | CLOUD_RESOURCE_MANAGER_EMULATOR_HOST=http://localhost:5380 | Limits: Organization and folder lifecycle, moves, search, and full ancestry: use Google Cloud; Creating an existing project ID returns that project, and deletion has no undelete; check those paths in Google Cloud. |
| Service Usage | SERVICE_USAGE_EMULATOR_HOST=http://localhost:5380 | Limits: Enable and disable switch a service for the whole local runtime, not one project. IAM, Resource Manager, and Service Usage stay enabled, and Google APIs that LocalCloud does not serve report ENABLED; Quotas, billing, and project-specific entitlements: validate in Google Cloud. |
| Cloud Billing | CLOUD_BILLING_EMULATOR_HOST=http://localhost:5380 | Limits: Cost totals and budget threshold notifications: validate in Google Cloud; Billing exports and budget-triggered automation: use Google Cloud. |
| Cloud Logging | CLOUD_LOGGING_EMULATOR_HOST=localhost:5380 | Limits: Filters cover the common Cloud Logging query fields; regular expressions and functions are refused. Logs-based metric definitions store configuration; values aren't derived locally; Sink updates and logs-based metrics are served over gRPC, not REST. |
| Cloud Monitoring | CLOUD_MONITORING_EMULATOR_HOST=localhost:5380 | Limits: Filters support =, != and : on metric type, resource type, and labels with AND, OR and NOT. Aggregation, alignment and orderBy are refused, so sort and aggregate raw points in your test; Alert evaluation, notifications, uptime checks, groups, and dashboards: validate in Google Cloud. |
| Cloud Storage | STORAGE_EMULATOR_HOST=http://localhost:5382 | Limits: Object versioning, archive events, soft delete, folders, and managed folders run locally; Retention policies, object holds, and local Cloud KMS keys are enforced. Lifecycle rules are stored; validate scheduled lifecycle actions in Google Cloud. |
| BigQuery | BIGQUERY_EMULATOR_HOST=http://localhost:5388 | Limits: Behavior varies with SQL, ML, and geography inputs; test your edge-case inputs. Policy-tag taxonomy import/export: validate in Google Cloud; BigQuery ML, JavaScript UDFs, and EXTERNAL_QUERY on Cloud SQL, AlloyDB, PostgreSQL, and MySQL need the full image (localcloud start --full). |
| Dataproc | DATAPROC_EMULATOR_HOST=localhost:5380 | Limits: Each cluster is one local Docker container. Docker daemon access is required; Serverless batches, workflow templates, autoscaling, automated node repair, and production SLAs: validate in Google Cloud. |
| Google Sheets | SHEETS_EMULATOR_HOST=http://localhost:5380 | Limits: Values come back as written: formulas aren't evaluated and render options are ignored; Spreadsheet metadata, append, clear, and batch updates: use Google Cloud. |
LocalCloud removes cloud dependencies from local development; it does not remove the responsibility to validate production behavior with real Google Cloud.
A hosted Markdown guide for agents: install-first quick start, rules, workflow, and endpoints.
Open Markdown guideAGENTS.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.
HTML pages stay canonical for humans; raw Markdown pages give agents compact service, compatibility, and docs context.
Reusable LocalCloud Agent Skills cover BigQuery, Pub/Sub, Terraform, internal automation, seed data, and SDK tests. Copy them into .agents/skills/ for a non-production project.
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.
http://localhost:5380 Inspect service health, local data, logs, and administrative state.
http://localhost:5380/health Inspect runtime health; use the readiness endpoint before application traffic.
http://localhost:5380/readiness Wait for configured services to be ready, then verify the exact SDK/API workflow.
http://localhost:5380/env?format=shell Set emulator endpoint variables for local SDK and CLI workflows.
http://localhost:5380/env?format=terraform Set endpoint overrides for local Terraform validation without real Google Cloud credentials.