# Give coding agents a local Google Cloud target > Everything an AI coding agent needs to use LocalCloud: an AGENTS.md template, copyable prompts, raw Markdown docs, and localhost SDK setup. > > Source: https://local.cloud/ai/ Agent-safe local GCP localcloud is cloud for agents for developers, platform/DevOps engineers and teams running CI, plus AI coding agent users. Individuals, teams, nonprofits, and companies can build and test with 25 Google Cloud services on localhost in one Docker container, without a 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. [Open raw agent guide](https://local.cloud/ai/agents.md) [Download AGENTS.md template](https://local.cloud/ai/agent-template.md) [Browse Agent Skills](https://github.com/LocalGCloud/LocalGCloud.github.io/tree/main/agent-skills) [Review compatibility](https://local.cloud/compatibility/) Canonical facts - **Docker image:** agentcloud/localcloud:latest - **Local services:** 25 - **Credentials:** No GCP account, credentials, or billing by default - **Production boundary:** Validate against real GCP before production - **Agent contact:** [agent@local.cloud](mailto:agent@local.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. Related pages - [Local cloud for AI agents](https://local.cloud/local-cloud-for-ai-agents/): Why an agent needs a cloud API target, not only a code sandbox. Local first ### Same SDKs, localhost endpoints Agents should keep project code pointed at standard Google Cloud SDKs while exporting emulator host variables for local runs. No secrets ### No GCP account by default Agents shouldn't ask for service-account keys, billing projects, or production credentials for local checks. Boundary ### 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 Prompt 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 Prompt 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 Prompt 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 Prompt 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 Prompt 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 Prompt 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 Prompt 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-only ``` 02 ### Confirm readiness Wait for the runtime readiness endpoint before any SDK, CLI, Terraform, or test command. ``` curl -fsS http://localhost:5380/readiness ``` 03 ### 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](https://local.cloud/services/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](https://local.cloud/services/bigtable/) custom-emulator | BIGTABLE\_EMULATOR\_HOST=localhost:5385 | Documented local workflows with these boundaries: Permissive IAM and one change-stream partition; no query statistics, view parameters, or legacy snapshots; Sink bypasses later filters and is invalid inside Condition; HLL++ and multi-column view keys use local encodings. | | [Spanner](https://local.cloud/services/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](https://local.cloud/services/alloydb/) local-facade | ALLOYDB\_EMULATOR\_HOST=localhost:5380 | Documented local workflows with these boundaries: Backup restore applies metadata; advanced engine behavior and replicas are unavailable; Managed regional failover requires Google Cloud. | | [Memorystore (Redis/Valkey)](https://local.cloud/services/memorystore/) 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](https://local.cloud/services/cloud-sql/) local-facade | CLOUD\_SQL\_EMULATOR\_HOST=http://localhost:5380 | Documented local workflows with these boundaries: Shared engines; version labels, instance flags, and infrastructure settings do not provision separate servers; Backups are metadata; export/import/restore/restart and replica verbs do no data work. Replace-restore and migration leave Cloud SQL untouched. | | [Pub/Sub](https://local.cloud/services/pubsub/) local-facade | PUBSUB\_EMULATOR\_HOST=localhost:5383 | Documented local workflows with these boundaries: No exactly-once delivery, message ordering, export subscriptions, or transforms; Push receivers must trust the local issuer/JWKS; retry and retention timing is approximate. | | [Cloud Tasks](https://local.cloud/services/cloud-tasks/) local-facade | CLOUD\_TASKS\_EMULATOR\_HOST=localhost:5380 | Documented local workflows with these boundaries: No App Engine dispatch or logging sampling; queue target overrides need exact-image validation; Authenticated receivers must trust the local issuer/JWKS. | | [Cloud Scheduler](https://local.cloud/services/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](https://local.cloud/services/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)](https://local.cloud/services/cloud-functions/) 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](https://local.cloud/services/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](https://local.cloud/services/compute-engine/) Unsupported local-facade | No local endpoint | Not available locally. Use Google Cloud for this service. | | [Cloud Run](https://local.cloud/services/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](https://local.cloud/services/vertex-ai/) Unsupported local-facade | No local endpoint | Not available locally. Use Google Cloud for this service. | | [Secret Manager](https://local.cloud/services/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](https://local.cloud/services/cloud-iam/) local-facade | IAM\_EMULATOR\_HOST=localhost:5380 | Documented local workflows with these boundaries: Enforcement depends on service, transport, and IAM mode; open/permissive mode is not access control; No full CEL, organization/folder ancestry, or deny policies; federation uses local OIDC providers. | | [Cloud KMS](https://local.cloud/services/cloud-kms/) local-facade | CLOUD\_KMS\_EMULATOR\_HOST=localhost:5380 | Documented local workflows with these boundaries: SOFTWARE keys; hardware custody and Google authority require Google Cloud; Inventory/Autokey covers project-owned global Secret Manager resources; no folder ancestry or other protected types. | | [Cloud Resource Manager](https://local.cloud/services/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](https://local.cloud/services/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](https://local.cloud/services/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](https://local.cloud/services/cloud-logging/) local-facade | CLOUD\_LOGGING\_EMULATOR\_HOST=localhost:5380 | Documented local workflows with these boundaries: Local filters cover a subset of Google syntax; metric definitions do not derive values; Validate exclusions and sink delivery in Google Cloud. | | [Cloud Monitoring](https://local.cloud/services/cloud-monitoring/) local-facade | CLOUD\_MONITORING\_EMULATOR\_HOST=localhost:5380 | Documented local workflows with these boundaries: Aggregation and order\_by are ignored; filters support AND-joined equality on metric/resource type and labels; Validate alert evaluation, notifications, uptime execution, and dashboards in Google Cloud. | | [Cloud Storage](https://local.cloud/services/cloud-storage/) third-party-emulator | STORAGE\_EMULATOR\_HOST=http://localhost:5382 | Documented local workflows with these boundaries: Versioning and archive events await image validation; managed folders are unavailable; Lifecycle, retention, holds, and encryption metadata are stored without enforcement. | | [BigQuery](https://local.cloud/services/bigquery/) custom-emulator | BIGQUERY\_EMULATOR\_HOST=http://localhost:5388 | Documented local workflows with these boundaries: SQL, ML, and geography have input-specific limits; ingestion-time pseudocolumn reads and nested policy tags are unavailable; External tables use local GCS; native Bigtable, Sheets, HTTP, and local-file sources are unavailable. | | [Dataproc](https://local.cloud/services/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](https://local.cloud/services/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. [Compatibility](https://local.cloud/compatibility/) [SDK examples](https://local.cloud/docs/sdk-examples/) [Terraform](https://local.cloud/docs/terraform/) [Seed data](https://local.cloud/docs/seed-data/) 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. Raw guide ## /ai/agents.md A hosted Markdown guide for agents: install-first quick start, rules, workflow, and endpoints. [Open Markdown guide](https://local.cloud/ai/agents.md) Repo-local policy ## AGENTS.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. [Download template](https://local.cloud/ai/agent-template.md) Markdown policy ## Raw resource index HTML pages stay canonical for humans; raw Markdown pages give agents compact service, compatibility, and docs context. - [/ai/services.md](https://local.cloud/ai/services.md): service matrix and endpoint variables - [/ai/compatibility.md](https://local.cloud/ai/compatibility.md): what each service runs locally - [/ai/docs.md](https://local.cloud/ai/docs.md): SDK, Terraform, seed data, and console docs [Open Markdown index](https://local.cloud/ai/resources.md) Portable skills ## 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. [Open skills repository](https://github.com/LocalGCloud/LocalGCloud.github.io/tree/main/agent-skills) 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](https://local.cloud/glossary/mcp-server/). ### 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.