Agent-safe local GCP

Give coding agents a local Google Cloud target

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 Download AGENTS.md template

Browse Agent Skills Review compatibility

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.

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.

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

Confirm readiness

Wait for the runtime readiness endpoint before any SDK, CLI, Terraform, or test command.

curl -fsS http://localhost:5380/readiness

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)"

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: 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 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 applies metadata; advanced engine behavior and replicas are unavailable; Managed regional failover requires Google Cloud.
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 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 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 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 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 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 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 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: Local filters cover a subset of Google syntax; metric definitions do not derive values; Validate exclusions and sink delivery in Google Cloud.
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 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 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 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.

Compatibility SDK examples Terraform 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

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

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: service matrix and endpoint variables
/ai/compatibility.md: what each service runs locally
/ai/docs.md: SDK, Terraform, seed data, and console docs

Open Markdown index

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

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.