LocalCloud Agent Resources: AGENTS.md Template and Prompts
Get started
local.cloud / agents
Read this page as Markdown ↗
local.cloud — Agent Resources: AGENTS.md Template and Prompts .md Open tab
Agent-safe local GCP

Give coding agents a local Google Cloud target

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.

Why it matters

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 non-production LocalCloud CI workflow.

Add a CI workflow

Prompt

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.

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 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.
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.
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.

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 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.

Desktop view