# LocalCloud agent execution guide

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.

This hosted guide is for coding agents that need a safe local Google Cloud target. For a repository-local policy file, copy the AGENTS.md template from https://local.cloud/ai/AGENTS.md into your project.

## Fast path
```bash
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:latest
eval "$(localcloud env)"
curl -fsS http://localhost:24080/health
```

## Boundaries
- Permitted workflows use local endpoint values and should stop rather than fall back to real Google Cloud or real credentials. The Public Preview License permits individuals and organizations, including for-profit companies, to use LocalCloud for non-production internal development, testing, CI, evaluation, and pilots.
- LocalCloud emulates bounded local development workflows. Validate application behavior against real Google Cloud before production deployment.
- Before production deployment, unset LocalCloud emulator environment variables and validate behavior against real Google Cloud.
- If Docker or LocalCloud is unavailable, stop instead of using real GCP as a fallback.

## Machine-readable working set
- **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.

## Service matrix
- **Cloud Storage** (Supported locally, HTTP/REST :24081) — set `STORAGE_EMULATOR_HOST=http://localhost:24081`. Local development coverage is partial. Known limits: [prod_only] IAM, lifecycle policies, and notifications not emulated in LocalCloud.. Docs: https://local.cloud/services/cloud-storage/
- **Pub/Sub** (Partial local coverage, gRPC :24082) — set `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.. Docs: https://local.cloud/services/pubsub/
- **Firestore** (Partial local coverage, gRPC :24083) — set `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.. Docs: https://local.cloud/services/firestore/
- **Bigtable** (Supported locally, gRPC :24084) — set `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.. Docs: https://local.cloud/services/bigtable/
- **Spanner** (Partial local coverage, gRPC :24085 · HTTP/REST :24086) — set `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.. Docs: https://local.cloud/services/spanner/
- **BigQuery** (Partial local coverage, HTTP/REST :24087 · gRPC :24088) — set `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.. Docs: https://local.cloud/services/bigquery/
- **Google Sheets** (Partial local coverage, HTTP/REST :24080) — set `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.. Docs: https://local.cloud/services/google-sheets/
- **Secret Manager** (Partial local coverage, gRPC :24080) — set `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.. Docs: https://local.cloud/services/secret-manager/
- **Cloud Tasks** (Partial local coverage, gRPC :24080) — set `CLOUD_TASKS_EMULATOR_HOST=localhost:24080`. Local development coverage is partial. Known limits: App Engine tasks and OAuth token generation are not complete.. Docs: https://local.cloud/services/cloud-tasks/
- **Cloud Scheduler** (Partial local coverage, gRPC :24080) — set `CLOUD_SCHEDULER_EMULATOR_HOST=localhost:24080`. Local development coverage is partial. Known limits: Timezone rules beyond cron-utils support are not fully verified.. Docs: https://local.cloud/services/cloud-scheduler/
- **Cloud Functions (2nd Gen)** (Partial local coverage, gRPC :24080) — set `CLOUD_FUNCTIONS_EMULATOR_HOST=localhost:24080`. Local development coverage is partial. Known limits: Build and container execution are metadata-only; use Functions Framework locally.. Docs: https://local.cloud/services/cloud-functions/
- **AlloyDB** (Partial local coverage, gRPC :24080) — set `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.. Docs: https://local.cloud/services/alloydb/
- **Dataproc** (Partial local coverage, gRPC :24080) — set `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.. Docs: https://local.cloud/services/dataproc/
- **Cloud IAM** (Partial local coverage, gRPC :24080) — set `IAM_EMULATOR_HOST=localhost:24080`. Local development coverage is partial. Known limits: Role validation, conditions, and deny policies are not complete.. Docs: https://local.cloud/services/cloud-iam/
- **Cloud Resource Manager** (Supported locally, HTTP/REST :24080) — set `CLOUD_RESOURCE_MANAGER_EMULATOR_HOST=http://localhost:24080`. Local development coverage is partial. Known limits: [prod_only] Organization/folder hierarchy not modeled in LocalCloud.. Docs: https://local.cloud/services/cloud-resource-manager/
- **Service Usage** (Partial local coverage, HTTP/REST :24080) — set `SERVICE_USAGE_EMULATOR_HOST=http://localhost:24080`. Local development coverage is partial. Known limits: Quotas and service entitlement behavior are stubs.. Docs: https://local.cloud/services/service-usage/
- **Cloud Billing** (Partial local coverage, HTTP/REST :24080) — set `CLOUD_BILLING_EMULATOR_HOST=http://localhost:24080`. Local development coverage is partial. Known limits: Real billing, budget enforcement, and cost export are not implemented.. Docs: https://local.cloud/services/cloud-billing/
- **Cloud Logging** (Partial local coverage, gRPC :24080) — set `CLOUD_LOGGING_EMULATOR_HOST=localhost:24080`. Local development coverage is partial. Known limits: Metrics, exclusions, audit logs, and production sink behavior are limited.. Docs: https://local.cloud/services/cloud-logging/
- **Cloud Monitoring** (Partial local coverage, gRPC :24080) — set `CLOUD_MONITORING_EMULATOR_HOST=localhost:24080`. Local development coverage is partial. Known limits: Alerting, uptime checks, and dashboards are partial.. Docs: https://local.cloud/services/cloud-monitoring/
- **GKE** (Partial local coverage, gRPC :24080 · k3d :24092) — set `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).. Docs: https://local.cloud/services/gke/
- **Compute Engine** (Partial local coverage, HTTP/REST :24080) — set `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.. Docs: https://local.cloud/services/compute-engine/
- **Cloud Run** (Partial local coverage, gRPC :24080) — set `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).. Docs: https://local.cloud/services/cloud-run/
- **Memorystore (Redis/Valkey)** (Partial local coverage, RESP :24089) — set `REDIS_HOST=localhost:24089`. Local development coverage is partial. Known limits: Pub/Sub, Lua, streams, and MULTI/EXEC are not supported.. Docs: https://local.cloud/services/memorystore/
- **Cloud Workflows** (Partial local coverage, gRPC :24080) — set `WORKFLOWS_EMULATOR_HOST=localhost:24080`. Local development coverage is partial. Known limits: In-flight execution checkpointing is not durable across restart.. Docs: https://local.cloud/services/cloud-workflows/
- **Vertex AI** (Partial local coverage, HTTP/REST :24080) — set `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.. Docs: https://local.cloud/services/vertex-ai/
- **Cloud KMS** (Partial local coverage, HTTP/REST :24080) — set `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.. Docs: https://local.cloud/services/cloud-kms/
- **Cloud SQL** (Partial local coverage, HTTP/REST :24080 · PostgreSQL :24090 · MySQL :24091) — set `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.. Docs: https://local.cloud/services/cloud-sql/

## Copy prompts
### Start LocalCloud
Use case: Give an agent one URL and have it start the local GCP sandbox.

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

### Configure this repo
Use case: Have an agent wire an existing project to LocalCloud safely.

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

### Configure internal CI
Use case: Have an agent add a permitted non-production LocalCloud CI workflow.

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

### Troubleshoot routing
Use case: Diagnose why SDKs or Terraform are still reaching real GCP.

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

### BigQuery local test
Use case: Ask an agent to validate BigQuery code against the local emulator.

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

### Pub/Sub local test
Use case: Ask an agent to validate Pub/Sub event code locally.

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

### Cloud Storage local test
Use case: Ask an agent to validate bucket/object code locally.

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

## Safe validation checklist
- 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.

## Human and agent links
- Human landing page: https://local.cloud/ai/
- AGENTS.md template: https://local.cloud/ai/AGENTS.md
- Markdown resource index: https://local.cloud/ai/resources.md
- Service catalog: https://local.cloud/services/
- Compatibility and limitations: https://local.cloud/compatibility/
- Product docs: https://local.cloud/docs/
- SDK examples: https://local.cloud/docs/sdk-examples/
- Terraform guide: https://local.cloud/docs/terraform/
- Seed data guide: https://local.cloud/docs/seed-data/
- Agent Skills package: https://github.com/LocalStack-Google/localcloud-site/tree/main/agent-skills