# LocalCloud

> LocalCloud is a local Google Cloud emulator: one Docker container that serves 25 Google Cloud services on localhost, so developers, CI jobs, and AI coding agents can run Google Cloud code without a GCP account, credentials, or billing.

- Runs BigQuery, Cloud Storage, Pub/Sub, Spanner, Bigtable, Firestore, Cloud SQL, Memorystore (Redis/Valkey), Dataproc, Cloud Run, and more in one container.
- Standard Google Cloud SDKs and Terraform connect through generated emulator environment variables.
- Stores local state in a named Docker volume and includes a web console for service health and local data.
- Installs as a CLI on macOS and Linux; any Docker host can run the container directly.
- Free during the public preview for non-production use, and free for open-source projects.

Use LocalCloud for development, testing, and CI, and validate application behavior against real Google Cloud before production deployment.

## Quick start

```bash
curl -fsSL https://local.cloud/install.sh | sh
localcloud doctor
localcloud start --local-only
curl -fsS http://localhost:5380/readiness
eval "$(localcloud env)"
localcloud console
```

- Homebrew alternative to the first line: `brew install LocalGCloud/tap/localcloud`.
- `localcloud start` waits for the runtime. The CLI remaps a default port when it is in use; use the URLs and endpoint values it returns.
- Without the CLI (for example on Windows), follow the [manual Docker path](https://local.cloud/docs/#manual-docker-path).

## Runtime facts

- Default project: `local-gcp-project`
- Default user: `local-developer`
- Default data volume: `localcloud-data`; select another with `--data-volume NAME`.
- CLI memory default: `4g`
- Readiness endpoint (wait for it before application traffic): `http://localhost:5380/readiness`
- Health endpoint: `http://localhost:5380/health`
- Shell environment: `http://localhost:5380/env?format=shell`
- Terraform environment: `http://localhost:5380/env?format=terraform`

## Agent resources

- [Agent guide](https://local.cloud/ai/agents.md): install-first quick start, rules, and workflow for coding agents
- [AGENTS.md template](https://local.cloud/ai/agent-template.md): repository instructions to copy into a project
- [Service matrix](https://local.cloud/ai/services.md): ports, environment variables, and guides
- [Capabilities and boundaries](https://local.cloud/ai/compatibility.md): what each service runs locally
- [Docs index for agents](https://local.cloud/ai/docs.md)
- [Full documentation](https://local.cloud/llms-full.txt): every docs page, service guide and comparison in one Markdown file
- [Agent Skills](https://github.com/LocalGCloud/LocalGCloud.github.io/tree/main/agent-skills): portable skills for `.agents/skills/`

## Docs

Every docs page, service guide and comparison also has a Markdown version: replace the trailing slash with `.md`, for example https://local.cloud/docs/configuration.md, https://local.cloud/services/bigquery.md and https://local.cloud/compare/google-emulators.md (the section pages are https://local.cloud/docs/index.md, https://local.cloud/services/index.md and https://local.cloud/compare/index.md).

- [Getting started](https://local.cloud/docs/): install, start, and make a first request
- [Configuration](https://local.cloud/docs/configuration/): services, projects, persistence, and networking
- [SDK examples](https://local.cloud/docs/sdk-examples/): Google Cloud client libraries against localhost
- [LocalCloud MCP](https://local.cloud/docs/mcp/): CLI 0.1.9+ setup, coding clients, agent workflows, tools, and troubleshooting
- [Terraform](https://local.cloud/docs/terraform/): provider endpoint overrides
- [Seed data](https://local.cloud/docs/seed-data/): repeatable local fixtures
- [Architecture](https://local.cloud/docs/architecture/)
- [Web console](https://local.cloud/docs/console/)
- [Service catalog](https://local.cloud/services/)
- [Compatibility and limitations](https://local.cloud/compatibility/)
- [FAQ](https://local.cloud/docs/faq/)
- [Privacy](https://local.cloud/docs/privacy/)

## Services

Every service in the table runs locally. Firestore, GKE, and Cloud Run are opt-in: `--services` sets the exact list of service IDs to run, for example `localcloud start --local-only --services firestore,bigtable,spanner`. Google Sheets serves read-only spreadsheet values as fixtures for other services. Bigtable, Spanner, GKE, Cloud Run, and Cloud KMS are Pro-tier services, marked "Pro tier, free during preview": they are free during the public preview and need no license key ([pricing](https://local.cloud/pricing/#pro-tier)).

| Service | ID | Starts by default | Endpoints | Environment variable | Guide |
| --- | --- | --- | --- | --- | --- |
| Firestore | `firestore` | opt-in | gRPC :5384 | `FIRESTORE_EMULATOR_HOST=localhost:5384` | [guide](https://local.cloud/services/firestore/) |
| Bigtable | `bigtable` | yes | gRPC :5385 | `BIGTABLE_EMULATOR_HOST=localhost:5385` | [guide](https://local.cloud/services/bigtable/) |
| Spanner | `spanner` | yes | gRPC :5386 · HTTP/REST :5387 | `SPANNER_EMULATOR_HOST=localhost:5386` | [guide](https://local.cloud/services/spanner/) |
| AlloyDB | `alloydb` | yes | gRPC :5380 | `ALLOYDB_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/alloydb/) |
| Memorystore (Redis/Valkey) | `memorystore` | yes | RESP :5390 | `REDIS_HOST=localhost:5390` | [guide](https://local.cloud/services/memorystore/) |
| Cloud SQL | `cloudsql` | yes | HTTP/REST :5380 · PostgreSQL :5391 · MySQL :5406 | `CLOUD_SQL_EMULATOR_HOST=http://localhost:5380` | [guide](https://local.cloud/services/cloud-sql/) |
| Pub/Sub | `pubsub` | yes | gRPC :5383 | `PUBSUB_EMULATOR_HOST=localhost:5383` | [guide](https://local.cloud/services/pubsub/) |
| Cloud Tasks | `cloudtasks` | yes | gRPC :5380 | `CLOUD_TASKS_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/cloud-tasks/) |
| Cloud Scheduler | `cloudscheduler` | yes | gRPC + HTTP/REST :5380 | `CLOUD_SCHEDULER_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/cloud-scheduler/) |
| Cloud Workflows | `workflows` | yes | gRPC :5380 | `WORKFLOWS_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/cloud-workflows/) |
| Cloud Functions (2nd Gen) | `cloudfunctions` | yes | gRPC :5380 | `CLOUD_FUNCTIONS_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/cloud-functions/) |
| GKE | `gke` | opt-in | gRPC :5380 · k3d :5443 | `GKE_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/gke/) |
| Cloud Run | `cloudrun` | opt-in | gRPC :5380 | `CLOUD_RUN_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/cloud-run/) |
| Secret Manager | `secretmanager` | yes | gRPC :5380 | `SECRET_MANAGER_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/secret-manager/) |
| Cloud IAM | `cloudiam` | yes | gRPC :5380 | `IAM_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/cloud-iam/) |
| Cloud KMS | `kms` | yes | gRPC + HTTP/REST :5380 | `CLOUD_KMS_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/cloud-kms/) |
| Cloud Resource Manager | `cloudresourcemanager` | yes | HTTP/REST :5380 | `CLOUD_RESOURCE_MANAGER_EMULATOR_HOST=http://localhost:5380` | [guide](https://local.cloud/services/cloud-resource-manager/) |
| Service Usage | `serviceusage` | yes | HTTP/REST :5380 | `SERVICE_USAGE_EMULATOR_HOST=http://localhost:5380` | [guide](https://local.cloud/services/service-usage/) |
| Cloud Billing | `cloudbilling` | yes | HTTP/REST :5380 | `CLOUD_BILLING_EMULATOR_HOST=http://localhost:5380` | [guide](https://local.cloud/services/cloud-billing/) |
| Cloud Logging | `logging` | yes | gRPC :5380 | `CLOUD_LOGGING_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/cloud-logging/) |
| Cloud Monitoring | `monitoring` | yes | gRPC :5380 | `CLOUD_MONITORING_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/cloud-monitoring/) |
| Cloud Storage | `gcs` | yes | HTTP/REST :5382 | `STORAGE_EMULATOR_HOST=http://localhost:5382` | [guide](https://local.cloud/services/cloud-storage/) |
| BigQuery | `bigquery` | yes | HTTP/REST :5388 · gRPC :5389 | `BIGQUERY_EMULATOR_HOST=http://localhost:5388` | [guide](https://local.cloud/services/bigquery/) |
| Dataproc | `dataproc` | yes | gRPC :5380 | `DATAPROC_EMULATOR_HOST=localhost:5380` | [guide](https://local.cloud/services/dataproc/) |
| Google Sheets | `sheets` | yes | HTTP/REST :5380 | `SHEETS_EMULATOR_HOST=http://localhost:5380` | [guide](https://local.cloud/services/google-sheets/) |

Unsupported locally; use Google Cloud:

- [Compute Engine](https://local.cloud/services/compute-engine/) — unsupported
- [Vertex AI](https://local.cloud/services/vertex-ai/) — unsupported

## License

The proprietary Public Preview License permits individuals and organizations, including for-profit companies, to use LocalCloud free of charge for internal development, testing, CI, evaluation, and internal pilots. Excluded uses: customer-facing or other production use; reselling LocalCloud or providing it as a hosted or managed service; redistribution or sublicensing; and modification except where applicable law requires permission. Open-source projects can use LocalCloud free of charge for development, testing, and ongoing internal CI under the Free for open-source projects policy, which continues after the public preview ends. Each preview release keeps its terms if the preview ends or a later release uses different terms.

- [Licensing](https://local.cloud/docs/licensing/): the terms in plain language
- [License text](https://local.cloud/license/): the full Public Preview License Agreement, also as [plain text](https://local.cloud/license.txt)
- [Pricing](https://local.cloud/pricing/)

## How LocalCloud compares

- LocalStack emulates AWS and Snowflake, not Google Cloud; teams on both clouds run both.
- Google ships separate emulators for Bigtable, Datastore, Firestore, Pub/Sub and Spanner through the Google Cloud CLI, and the Firebase Local Emulator Suite for Firebase products. The Google Cloud CLI has no BigQuery or Cloud Storage emulator.
- Single-service community emulators typically cover one Google Cloud service each, such as BigQuery or Cloud Storage; coverage and fidelity vary by project.
- LocalCloud runs 25 Google Cloud services, including BigQuery and Cloud Storage, in one Docker container, using Google's Firestore emulator and a Spanner emulator built from Google's open-source emulator.
- [Full comparison with sources](https://local.cloud/compare/), reviewed 2026-10-05, and [LocalStack for Google Cloud](https://local.cloud/localstack-for-google-cloud/).

## Contact

- AI agents and integrations: agent@local.cloud
- People (general, licensing, privacy, partnerships): info@local.cloud, or [the contact page](https://local.cloud/contact/)
- Security reports: info@local.cloud with the subject "Security report"; see [Security](https://local.cloud/security/)
- Bugs and feature requests: [CLI issues on GitHub](https://github.com/LocalGCloud/localcloud-cli/issues)

## Optional

- [Changelog](https://local.cloud/changelog/): CLI releases with dates
- [About LocalCloud Inc.](https://local.cloud/about/)
- [Local cloud for AI agents](https://local.cloud/local-cloud-for-ai-agents/)
- [Agent sandbox setup](https://local.cloud/agents/)
- [Agent and automation workflows](https://local.cloud/workflows/)
- [Comparisons and alternatives](https://local.cloud/compare/)
- [Glossary](https://local.cloud/glossary/)
- [Blog](https://local.cloud/blog/)
- [CLI releases](https://github.com/LocalGCloud/localcloud-cli/releases)

---

The sections below are the Markdown versions of every docs page, service guide and comparison on https://local.cloud/, in reading order. Each section names its source page.

---

## Get started with LocalCloud

> Install the LocalCloud CLI, start a local runtime, and make your first Cloud Storage request.
>
> Source: https://local.cloud/docs/

This tutorial installs the LocalCloud CLI, starts a persistent local runtime, configures this shell, and verifies a Cloud Storage request. LocalCloud runs local versions of Google Cloud services for development and testing. Before you deploy to production, run final validation against real Google Cloud.

### Prerequisites

- Docker Desktop, Colima, or Docker Engine is installed **and running**.
- A supported native CLI host: macOS 13+ or Linux with glibc 2.35+, on ARM64 or AMD64.
- `curl`, `tar`, `sed`, `sort`, and either `sha256sum` or `shasum`.

The CLI is a standalone executable and does not require Python. Windows users should use the [manual Docker fallback](https://local.cloud/docs/#manual-docker-path).

### Install the CLI

Install script:

```bash
curl -fsSL https://local.cloud/install.sh | sh
```

Homebrew:

```bash
brew install LocalGCloud/tap/localcloud
```

The install script downloads the appropriate macOS or Linux release, verifies its SHA-256 checksum, validates the exact archive members, and runs the executable to confirm its semantic version. Release automation separately publishes Sigstore bundles, but `install.sh` does not verify those bundles.

In an interactive terminal, the installer can offer to run diagnostics and start LocalCloud after you confirm. In automation or with `--no-start`, it prints absolute-path next steps instead. If it adds the CLI to your shell startup file, run the exact `source` command printed by the installer before continuing.

> **Check your CLI version**
>
> Run `localcloud --version` to see which release you have installed; the [changelog](https://local.cloud/changelog/) lists every release.

### Start your first runtime

#### Check Docker

```bash
localcloud doctor
```

A usable Docker installation exits successfully and reports `status: ok`. `doctor` diagnoses Docker; it does not install or start Docker Desktop, Colima, or Docker Engine. Add `--verbose` when you need the complete JSON payload.

#### Start LocalCloud

```bash
localcloud start --local-only
```

A successful command reports `started`, `already_running`, `restarted`, or `reconfigured`.

The runtime starts with the [built-in defaults](https://local.cloud/docs/configuration/#built-in-defaults).

[Runtime selection](https://local.cloud/docs/configuration/#runtime-selection) explains which data volume, and so which runtime, a command uses.

The example selects `--local-only`, which binds published ports to `127.0.0.1`. Without that flag, the current CLI publishes ports on all host interfaces. Use it again on subsequent `start`, `restart`, and `reset` commands to retain loopback binding. If a default port is already in use, the CLI can remap host ports. Use `--verbose` to inspect the complete runtime payload, including immutable container ID, ownership, image identity, mount details, and `sdk_env`.

#### Configure this shell

```bash
eval "$(localcloud env)"
```

`localcloud env` discovers the compatible running container using the selected data volume and prints local-only SDK settings with its actual mapped ports. It rejects environment values that would route supported services to real Google endpoints or non-loopback HTTP endpoints.

#### Open the console

```bash
localcloud console
```

The CLI opens the console for the selected runtime, project, and caller. Trust the returned `url`; do not replace it with a hard-coded port.

### Make your first API call

Install the Python Cloud Storage client if needed, then run this repeatable example in the same shell where you evaluated `localcloud env`:

```bash
python -m pip install google-cloud-storage
```

```python
from google.api_core.exceptions import NotFound
from google.cloud import storage

client = storage.Client(project="local-gcp-project")
bucket = client.bucket("localcloud-quickstart")

try:
    bucket.reload()
except NotFound:
    bucket.create()

blob = bucket.blob("hello.txt")
blob.upload_from_string("Hello, LocalCloud!")
print(blob.download_as_text())
```

The example safely reuses the same local bucket and overwrites the same object, so it can run repeatedly with the default persistent volume. The expected output is:

```text
Hello, LocalCloud!
```

If the SDK tries to contact Google Cloud, stop instead of adding real credentials. Re-run `eval "$(localcloud env)"` in the shell or process that launches the application.

### Verify and manage the runtime

```bash
localcloud status --verbose
localcloud logs --tail 50
```

[Stop, reset, and uninstall](https://local.cloud/docs/configuration/#stop-reset-and-uninstall) explains what `localcloud stop`, `localcloud reset` and the installer’s `--uninstall` keep and remove.

### Manual Docker path

Use this fallback on unsupported CLI hosts or when you deliberately do not want the host CLI. The `latest` tag is mutable, so prefer the CLI for normal use and pin an image digest when repeatability matters.

```bash
docker volume create localcloud-data

docker run -d --name localcloud \
  -p 127.0.0.1:5380-5405:5380-5405 \
  -m 4g \
  -v localcloud-data:/var/lib/localcloud \
  agentcloud/localcloud:latest
```

Verify the runtime and configure the shell through root operator endpoints:

```bash
curl -fsS http://localhost:5380/readiness
eval "$(curl -fsS 'http://localhost:5380/env?format=shell')"
```

The default command does not mount `/var/run/docker.sock` and does not expose ports on every host interface. Docker-backed service execution and custom companion images can require Docker-socket access; transparent DNS/HTTPS routing is also opt-in. Configure those capabilities only after reviewing their security implications.

### Next steps

[Configuration Select services, projects, persistence, and optional networking behavior.](https://local.cloud/docs/configuration/)[SDK Examples Configure supported client libraries using local endpoint values.](https://local.cloud/docs/sdk-examples/)[Service Catalog Browse all 27 available service guides and their documented limitations.](https://local.cloud/services/)[Compatibility Check which operations each service supports before you rely on them.](https://local.cloud/compatibility/)[Seed Data Pre-populate supported services with deterministic test data.](https://local.cloud/docs/seed-data/)[Terraform Choose endpoint-only or transparent-network Terraform setup.](https://local.cloud/docs/terraform/)

---

## Configuration

> Configure LocalCloud projects, services, storage, TLS, and service-owned runtime behavior.
>
> Source: https://local.cloud/docs/configuration/

The LocalCloud CLI reads `localcloud.yaml`, starts the Docker runtime, and returns the endpoints assigned to that runtime. Start with the defaults, then add only the settings you need.

```bash
localcloud start --local-only
eval "$(localcloud env)"
```

### Built-in defaults

Without a configuration file or flags, `localcloud start` uses:

- project `local-gcp-project`
- caller `local-developer`
- persistent data
- Docker access mode **auto**: the socket is mounted only when selected services require it; set `host.docker_socket: false` to opt out
- transparent networking **off**
- gateway TLS **off**; enable it explicitly when needed

### Create `localcloud.yaml`

The configuration format is versioned (`version: 1`) and logically structured by lifecycle scope:

```yaml
version: 1

context:
  project: local-gcp-project
  user: local-developer

host:
  data_volume: localcloud-data
  data: persistent
  docker_socket: auto
  memory: 4g
  transparent_network: false
  environment: {}

tls:
  enabled: false
  port: 5381

services:
  enabled: default

server:
  gateway:
    port: 5380
  logging:
    verbosity: info
  persistence: true
  auto_seed: true
```

Run `localcloud start` from the directory containing the file, or pass another file explicitly:

```bash
localcloud start ./config/personal-localcloud.yaml --local-only
```

Configuration file selection uses this order:

1. Explicit positional path, such as `localcloud start ./config/personal-localcloud.yaml --local-only`.
2. `LOCALCLOUD_CONFIG`.
3. `./localcloud.yaml`.
4. The runtime’s remembered configuration path.
5. `$HOME/.localcloud/localcloud.yaml`.
6. Built-in defaults.

The file is a recursive overlay: omitted values inherit defaults and mapping members set to `null` are deleted. Command-line flags override their corresponding fields. An explicit, environment, or remembered path that is missing fails rather than silently falling back.

The current unflagged CLI publishes ports on all host interfaces. Use `--local-only` on `start`, `restart`, and `reset` to select loopback binding. `host.docker_socket: auto` mounts the host socket when enabled services declare a Docker dependency; `false` is a hard opt-out.

> **Schema Migration**
>
> Legacy flat top-level keys such as `project:`, `data_volume:`, and `server.iam:` are rejected. Use hierarchical keys: `context.project`, `host.data_volume`, and service-owned configurations under `services.catalog.<service>.config`.

### Runtime selection

A runtime is identified by its Docker data volume. Runtime commands select one in this order:

1. `--data-volume NAME`, accepted by any runtime command, which selects an isolated durable runtime identity and its storage.
2. The selected configuration’s `host.data_volume`.
3. The active-runtime record, revalidated before use.
4. The built-in `localcloud-data` fallback.

* * *

### Select services

Use the default service selection:

```yaml
services:
  enabled: default
```

Or declare an explicit list of services to run:

```yaml
services:
  enabled:
    - gcs
    - bigquery
    - spanner
    - pubsub
```

The registry contains 27 API surfaces, including the auxiliary Google Sheets fixture integration. 22 are selected by default. Registry availability and default selection do not establish operation support or readiness. The currently unsupported entries are Compute Engine, Vertex AI. Check each service’s operation boundaries before use.

The default-disabled entries are Firestore, GKE, Compute Engine, Cloud Run, Vertex AI. Review the operation matrix before enabling them.

| Service ID | Service Name | Starts by Default | Minimum Tier |
| --- | --- | --- | --- |
| `firestore` | Firestore | no | Community |
| `bigtable` | Bigtable | yes | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) |
| `spanner` | Spanner | yes | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) |
| `alloydb` | AlloyDB | yes | Community |
| `memorystore` | Memorystore (Redis/Valkey) | yes | Community |
| `cloudsql` | Cloud SQL | yes | Community |
| `pubsub` | Pub/Sub | yes | Community |
| `cloudtasks` | Cloud Tasks | yes | Community |
| `cloudscheduler` | Cloud Scheduler | yes | Community |
| `workflows` | Cloud Workflows | yes | Community |
| `cloudfunctions` | Cloud Functions (2nd Gen) | yes | Community |
| `gke` | GKE | no | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) |
| `compute` | Compute Engine | no | — |
| `cloudrun` | Cloud Run | no | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) |
| `vertexai` | Vertex AI | no | — |
| `secretmanager` | Secret Manager | yes | Community |
| `cloudiam` | Cloud IAM | yes | Community |
| `kms` | Cloud KMS | yes | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) |
| `cloudresourcemanager` | Cloud Resource Manager | yes | Community |
| `serviceusage` | Service Usage | yes | Community |
| `cloudbilling` | Cloud Billing | yes | Community |
| `logging` | Cloud Logging | yes | Community |
| `monitoring` | Cloud Monitoring | yes | Community |
| `gcs` | Cloud Storage | yes | Community |
| `bigquery` | BigQuery | yes | Community |
| `dataproc` | Dataproc | yes | Community |
| `sheets` | Google Sheets (Auxiliary integration API) | yes | Community |

* * *

### Service-owned runtime configuration

LocalCloud delegates service tuning to service-owned runtime config blocks under `services.catalog.<id>.config`. You can customize resource budgets, logging levels, and engine behavior without rebuilding container images:

```yaml
version: 1

services:
  catalog:
    bigquery:
      config:
        memory_limit: 1GB
        threads: 4
        log_level: info
    memorystore:
      config:
        max_memory: 1gb
        max_memory_policy: volatile-lru
    cloudsql:
      config:
        mysql_max_connections: 100
        mysql_innodb_buffer_pool_size: 128M
    cloudiam:
      config:
        mode: open
        log_warnings: true
    spanner:
      config:
        backup_enabled: true
        backup_interval_seconds: 60
```

#### Supported service settings

| Service | Setting Key | Default | Description |
| --- | --- | --- | --- |
| **BigQuery** | `memory_limit` | `512MB` | Maximum DuckDB columnar OLAP memory budget. |
|  | `threads` | `2` | Worker threads allocated for analytical query execution. |
|  | `log_level` | `info` | Logging verbosity for the GoogleSQL engine. |
| **Cloud IAM** | `mode` | `open` | IAM evaluation mode (`open`, `permissive`, or `strict`). |
|  | `log_warnings` | `true` | Log evaluation warnings for missing or incomplete roles. |
| **Cloud SQL** | `mysql_max_connections` | `50` | Connection pool limit for MySQL 8.4 companion. |
|  | `mysql_innodb_buffer_pool_size` | `64M` | Memory pool allocated for MySQL InnoDB caching. |
| **Memorystore** | `max_memory` | `512mb` | Redis memory capacity limit. |
|  | `max_memory_policy` | `noeviction` | Eviction strategy when memory limit is reached. |
| **Spanner** | `backup_enabled` | `false` | Enable automated background backup schedule worker. |
|  | `backup_interval_seconds` | `60` | Sweep interval for backup schedules. |

* * *

### Environment variable overrides

Documented runtime environment overrides can take precedence over corresponding runtime fields. Do not infer an override from a naming pattern; use the service configuration reference. `LOCALCLOUD_CONFIG`, CLI context flags, and runtime overrides have different owners.

| Variable | Default | Purpose |
| --- | --- | --- |
| `LOCALCLOUD_PROJECT` | `local-gcp-project` | Default Google Cloud project ID. |
| `LOCALCLOUD_DATA_DIR` | `/var/lib/localcloud` | Base path for persistent emulator data inside the container. |
| `LOCALCLOUD_PERSISTENCE` | `true` | Retain state across container restarts on mounted volumes. |
| `LOCALCLOUD_SERVICES` | `default` | Comma-separated list of enabled service IDs. |
| `LOCALCLOUD_IAM_MODE` | `open` | Default Cloud IAM evaluation mode (`open`, `permissive`, `strict`). |
| `LOCALCLOUD_BIGQUERY_MEMORY_LIMIT` | `512MB` | Override BigQuery DuckDB memory budget. |
| `LOCALCLOUD_TELEMETRY` | `true` | Anonymous runtime diagnostic metrics preference. |

You can also specify environment variables inside `localcloud.yaml` under `host.environment`:

```yaml
host:
  environment:
    LOCALCLOUD_TELEMETRY: "false"
    LOCALCLOUD_BIGQUERY_MEMORY_LIMIT: "2GB"
```

* * *

### TLS and transparent networking

LocalCloud provides native TLS termination on port **5381** (or custom configured port):

```yaml
version: 1

tls:
  enabled: true
  port: 5381

host:
  transparent_network: false
```

- **Loopback Ports (Default)**: Services listen on published canonical ports **5380–5405**. Client SDKs use generated values, including the URL scheme where required (e.g. `STORAGE_EMULATOR_HOST=http://localhost:5382`). Some clients need explicit endpoint options.
- **Transparent Networking**: Uses local DNS on UDP port `5410` (mapped to host `53/udp`), routing standard Google Cloud domains (`storage.googleapis.com`, `bigquery.googleapis.com`) directly to LocalCloud.

* * *

### Stop, reset, and uninstall

What each lifecycle action keeps and removes:

- `localcloud stop` stops the runtime that [runtime selection](https://local.cloud/docs/configuration/#runtime-selection) picks and retains persistent storage.
- `localcloud reset --all-projects` prints manual recreation steps and deletes nothing.
- The CLI may operate a compatible container created by another tool, but never removes or relabels Docker resources it does not own.
- Running the installer with `--uninstall` removes only a script-managed CLI and its PATH block; containers and persistent volumes remain intact.

* * *

### Manual Docker execution

If running without the LocalCloud CLI, launch the container using the canonical **5380–5405** port range:

```yaml
services:
  localcloud:
    image: agentcloud/localcloud:latest
    ports:
      - "127.0.0.1:5380-5405:5380-5405"
    environment:
      LOCALCLOUD_PROJECT: local-gcp-project
      LOCALCLOUD_PERSISTENCE: "true"
    volumes:
      - localcloud-data:/var/lib/localcloud
    deploy:
      resources:
        limits:
          memory: 4g

volumes:
  localcloud-data:
```

### Sample data ownership

Container startup owns automatic samples. Set `server.auto_seed: false` to disable bootstrap samples. The retired `host.seed` setting is accepted but ignored, and managed CLI lifecycle commands do not mount or apply `seed.yaml`. Use the [seed endpoints](https://local.cloud/docs/seed-data/) for explicit fixtures and the Console Re-seed Data action for sample replacement.

---

## SDK examples

> Route standard Google Cloud SDK clients to LocalCloud and run local checks.
>
> Source: https://local.cloud/docs/sdk-examples/

LocalCloud accepts selected Google Cloud SDK workflows, but compatibility is service- and operation-specific. Start the runtime and load the endpoint values generated for the selected data volume before running any example:

```bash
localcloud start --local-only
eval "$(localcloud env)"
```

Do not hard-code default ports when using the host CLI: if a default port is already in use, the CLI picks another one. Run examples in the same shell or inject the generated variables into the test process. If a client tries to contact real Google Cloud, stop rather than adding real credentials.

### Cloud Storage: Python

This example is repeatable against a persistent local volume:

```python
import os
from google.api_core.exceptions import NotFound
from google.auth.credentials import AnonymousCredentials
from google.cloud import storage

assert os.environ['STORAGE_EMULATOR_HOST']
client = storage.Client(
    project=os.environ['GOOGLE_CLOUD_PROJECT'],
    credentials=AnonymousCredentials(),
)
bucket = client.bucket("localcloud-sdk-example")

try:
    bucket.reload()
except NotFound:
    bucket.create()

blob = bucket.blob("data.txt")
blob.upload_from_string("Hello from LocalCloud!")
print(blob.download_as_text())
```

### Cloud Storage: Node.js

```javascript
const { Storage } = require('@google-cloud/storage');

if (!process.env.STORAGE_EMULATOR_HOST || !process.env.GOOGLE_CLOUD_PROJECT) {
  throw new Error('Export the LocalCloud environment before running this example.');
}
const storage = new Storage({ projectId: process.env.GOOGLE_CLOUD_PROJECT });
const bucket = storage.bucket('localcloud-sdk-example');

async function main() {
  const [exists] = await bucket.exists();
  if (!exists) await storage.createBucket(bucket.name);
  await bucket.file('data.txt').save('Hello from LocalCloud!');
  const [content] = await bucket.file('data.txt').download();
  console.log(content.toString());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

### Pub/Sub: Python

Create unique test resources so repeated runs receive their own message, then delete the topic and subscription.

```python
import os
from uuid import uuid4
from google.cloud import pubsub_v1

assert os.environ['PUBSUB_EMULATOR_HOST']
project = os.environ['GOOGLE_CLOUD_PROJECT']
publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
name = 'hello-' + uuid4().hex[:12]
topic = publisher.topic_path(project, name)
subscription = subscriber.subscription_path(project, name)

publisher.create_topic(request={'name': topic}, timeout=30)
try:
    subscriber.create_subscription(request={'name': subscription, 'topic': topic}, timeout=30)
    try:
        publisher.publish(topic, b'Hello, Pub/Sub!').result(timeout=30)
        response = subscriber.pull(request={'subscription': subscription, 'max_messages': 1}, timeout=30)
        assert response.received_messages
        for received in response.received_messages:
            print(received.message.data.decode())
            subscriber.acknowledge(request={'subscription': subscription, 'ack_ids': [received.ack_id]}, timeout=30)
    finally:
        subscriber.delete_subscription(request={'subscription': subscription}, timeout=30)
finally:
    publisher.delete_topic(request={'topic': topic}, timeout=30)
    subscriber.close()
    publisher.transport.close()
```

### BigQuery: deterministic query

The Python BigQuery client needs an explicit REST API endpoint. Read the generated variable, then pass it through `client_options` with anonymous credentials. A missing variable fails before a client is created. [Client configuration reference](https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.client.Client).

```python
import os
from google.auth.credentials import AnonymousCredentials
from google.cloud import bigquery

client = bigquery.Client(
    project=os.environ['GOOGLE_CLOUD_PROJECT'],
    credentials=AnonymousCredentials(),
    client_options={"api_endpoint": os.environ["BIGQUERY_EMULATOR_HOST"]},
)
rows = list(client.query("SELECT 'Hello from LocalCloud!' AS message").result(timeout=30))
assert rows[0].message == 'Hello from LocalCloud!'
print(rows[0].message)
client.close()
```

See the [BigQuery guide](https://local.cloud/docs/bigquery-emulator-features/) and [coverage matrix](https://local.cloud/docs/bigquery-emulator-features/#coverage-matrix) for details on BQML, vector search, RLS, and the Storage Read API.

### Bigtable: Python

Create a test-owned instance and table, write a cell, and read the exact bytes back. This example follows the upstream Bigtable integration guide. Review [Bigtable workflows and boundaries](https://local.cloud/services/bigtable/#workflows) before running it.

```python
import os
from uuid import uuid4
from google.cloud import bigtable

assert os.environ['BIGTABLE_EMULATOR_HOST']
client = bigtable.Client(project=os.environ['GOOGLE_CLOUD_PROJECT'], admin=True)
instance = client.instance('guide-' + uuid4().hex[:12])
instance.create(clusters=[instance.cluster('local', location_id='us-central1-a', serve_nodes=1)]).result(timeout=60)
try:
    table = instance.table('messages')
    table.create(column_families={'cf': None})
    row = table.direct_row(b'row-1')
    row.set_cell('cf', b'message', b'hello')
    row.commit()
    message = table.read_row(b'row-1').cells['cf'][b'message'][0].value
    assert message == b'hello'
    print(message.decode())
    table.delete()
finally:
    instance.delete()
    client.close()
```

### Spanner: Python

Create a test-owned instance and database, apply DDL, write a row, and query it through the native SDK. Review [Spanner workflows and boundaries](https://local.cloud/services/spanner/#workflows) for the operations and recovery behavior your application needs.

```python
import os
from uuid import uuid4
from google.cloud import spanner

assert os.environ['SPANNER_EMULATOR_HOST']
client = spanner.Client(project=os.environ['GOOGLE_CLOUD_PROJECT'])
instance = client.instance('guide-' + uuid4().hex[:12], configuration_name='projects/' + client.project + '/instanceConfigs/emulator-config', display_name='Guide', node_count=1)
instance.create().result(timeout=60)
try:
    database = instance.database('messages', ddl_statements=['CREATE TABLE Messages (Id INT64 NOT NULL, Message STRING(100)) PRIMARY KEY (Id)'])
    database.create().result(timeout=60)
    with database.batch() as batch:
        batch.insert('Messages', columns=('Id', 'Message'), values=[(1, 'hello')])
    with database.snapshot() as snapshot:
        rows = list(snapshot.execute_sql('SELECT Message FROM Messages WHERE Id = 1'))
        assert rows == [['hello']]
        print(rows[0][0])
    database.drop()
finally:
    instance.delete()
    client.close()
```

### Firestore: Python

Enable Firestore before loading environment variables; it is disabled by default. Wait for readiness in the [setup guide](https://local.cloud/docs/), then run the example in the same shell:

```bash
localcloud start --local-only --services firestore
eval "$(localcloud env)"
```

This example creates, reads, updates, and deletes one unique document in the default database. Review [Firestore workflows and boundaries](https://local.cloud/services/firestore/#workflows) before expanding it to transactions or listeners.

```python
import os
from uuid import uuid4
from google.cloud import firestore

assert os.environ['FIRESTORE_EMULATOR_HOST']
client = firestore.Client(project=os.environ['GOOGLE_CLOUD_PROJECT'])
document = client.collection('guide').document(uuid4().hex)
try:
    document.set({'message': 'hello'}, timeout=30)
    message = document.get(timeout=30).get('message')
    assert message == 'hello'
    print(message)
    document.update({'message': 'updated'}, timeout=30)
    assert document.get(timeout=30).get('message') == 'updated'
finally:
    document.delete(timeout=30)
    client.close()
```

### Selecting another project

Generated environment output uses the configured project. Manual-Docker users can select an explicit project in the request:

```bash
eval "$(curl -fsS 'http://localhost:5380/env?format=shell&project=my-local-project')"
```

Keep client project IDs consistent with the generated `GOOGLE_CLOUD_PROJECT` value.

### Production validation

Local checks cover only documented workflows. Before production deployment:

1. Start a clean process without LocalCloud emulator or custom-endpoint variables.
2. Intentionally configure an isolated real Google Cloud project and credentials.
3. Run production-bound integration tests for IAM, quotas, networking, regional behavior, concurrency, recovery, and unsupported operations.

Do not treat protocol similarity or a passing emulator test as full Google Cloud parity. Organization and team-CI use must also comply with the governing proprietary license.

---

## Terraform integration

> Configure Terraform for supported LocalCloud resources using generated endpoints or transparent networking.
>
> Source: https://local.cloud/docs/terraform/

LocalCloud can exercise selected `hashicorp/google` resources locally. Support depends on the resource and routing mode; a successful local apply does not prove production Google Cloud behavior.

> **Check the supported resource list**
>
> The maintained examples use `hashicorp/google ~> 7.0` (including 7.34.0). Provider v7 requires a syntactically valid fake service-account JSON file; `/dev/null` is not sufficient. Some resources ignore custom endpoints and require transparent DNS/HTTPS routing plus a trusted LocalCloud CA.

### Choose a routing mode

#### Endpoint-only

Use endpoint-only mode for resources whose Google provider clients honor generated custom endpoints. Put Terraform mode in the CLI configuration **before** starting the runtime:

```yaml
# localcloud.yaml
version: 1
host:
  environment:
    LOCALCLOUD_TERRAFORM_MODE: "true"
```

```bash
localcloud start --local-only
eval "$(localcloud env --format terraform)"
export GOOGLE_APPLICATION_CREDENTIALS="$PWD/.localcloud/fake-service-account.json"
curl -fsS http://localhost:5380/terraform/readiness?mode=endpoint
terraform init
terraform plan
```

When the CLI remaps the gateway port, use the readiness URL it returns rather than hard-coding `5380`.

#### Transparent network

Use transparent networking only when required, notably for BigQuery and other clients that ignore custom endpoints. Configure both settings before `localcloud start`:

```yaml
# localcloud.yaml
version: 1
host:
  transparent_network: true
  environment:
    LOCALCLOUD_TERRAFORM_MODE: "true"
tls:
  enabled: true
  port: 5381
```

It requires:

- transparent networking enabled at start;
- host DNS routing for the required `*.googleapis.com` names;
- host `53/udp` routed to container `5410/udp`, host `80` routed to gateway `5380`, and host `443` routed to `tls.port` (default `5381`);
- the LocalCloud CA trusted by the Terraform process; and
- `LOCALCLOUD_TERRAFORM_MODE=true` in the runtime.

Verify the dedicated gate:

```bash
curl -fsS http://localhost:5380/terraform/readiness?mode=transparent
```

These host/network changes can affect other processes. Use an isolated personal environment and remove the DNS/trust configuration afterward.

### Create valid fake credentials

Use a generated private key and a syntactically valid service-account document. These are fake local credentials and must never be uploaded or reused for Google Cloud.

```bash
mkdir -p .localcloud
openssl genrsa -out .localcloud/fake-key.pem 2048 2>/dev/null
node scripts/create-localcloud-fake-sa.mjs \
  .localcloud/fake-key.pem \
  .localcloud/fake-service-account.json
chmod 600 .localcloud/fake-key.pem .localcloud/fake-service-account.json
export GOOGLE_APPLICATION_CREDENTIALS="$PWD/.localcloud/fake-service-account.json"
```

The referenced helper is provided in this site repository for a deterministic, JSON-safe credential fixture. Add `.localcloud/` to `.gitignore` in projects that copy this workflow.

### Provider configuration

```hcl
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 7.0"
    }
  }
}

provider "google" {
  project = "local-gcp-project"
  region  = "us-central1"
}
```

Use a non-production backend and project. Keep LocalCloud endpoint variables scoped to the local Terraform shell/job.

### Generated endpoint shapes

Generate the complete values from the running LocalCloud runtime:

```bash
eval "$(curl -fsS 'http://localhost:5380/env?format=terraform')"
```

Important generated shapes include:

| Variable | Canonical value/shape | Note |
| --- | --- | --- |
| `GOOGLE_STORAGE_CUSTOM_ENDPOINT` | `http://localhost:5382/storage/v1/` | Includes the Storage API path and trailing slash. |
| `GOOGLE_PUBSUB_CUSTOM_ENDPOINT` | `http://localhost:5380/` | Uses the gateway, not direct emulator port `5383`. |
| `GOOGLE_BIGTABLE_CUSTOM_ENDPOINT` | `http://localhost:5380/` | Terraform REST path uses the gateway; `BIGTABLE_EMULATOR_HOST` remains separately exported. |
| `GOOGLE_SPANNER_CUSTOM_ENDPOINT` | `http://localhost:5387/v1/` | Port `5387` is REST/grpc-gateway, not PostgreSQL wire. |
| `GOOGLE_CLOUD_TASKS_CUSTOM_ENDPOINT` | `http://localhost:5380/v2/` | Facade-specific version prefix. |
| `GOOGLE_BIGQUERY_CUSTOM_ENDPOINT` | `http://localhost:5388/` | The maintained provider path ignores this override; use transparent routing. |
| `GOOGLE_APPLICATION_CREDENTIALS` | `/dev/null` in generated output | Override it with the valid fake JSON file for provider v7. |

Do not hand-maintain a complete endpoint table; `/env?format=terraform` is derived from the enabled runtime registry and may include additional facade-specific paths.

### Supported Terraform resources

Maintained LocalCloud examples cover:

- `google_project`;
- `google_secret_manager_secret`;
- `google_secret_manager_secret_version`;
- `google_cloud_tasks_queue`;
- `google_sql_database_instance`;
- `google_sql_database`; and
- `google_sql_user`.

Rely on the resources listed above, or on resources whose service page documents the exact operation. BigQuery requires transparent routing. IAM, organization policy, quotas, regional managed behavior, networking, and production recovery must be validated in Google Cloud.

### Terraform mode and seed data

Set `LOCALCLOUD_TERRAFORM_MODE=true` in the **runtime container** for Terraform-managed resources. Seed operations are skipped to avoid creating resources outside Terraform state. The dedicated `/terraform/readiness` response checks routing prerequisites; generic `/health` alone is insufficient.

### Cleanup and production validation

```bash
terraform destroy -auto-approve
unset GOOGLE_APPLICATION_CREDENTIALS
# Start a clean process before any real-Google-Cloud validation.
```

Do not merely unset a few endpoint variables in a long-lived shell. Use a clean environment, explicitly configure an isolated real project and credentials, review the plan, and validate IAM, networking, and quota behavior against Google Cloud before release. Review the governing proprietary license before using LocalCloud.

Confirm `/terraform/readiness` succeeds for the routing mode you selected before running `terraform plan` or `terraform apply`.

---

## Seed data

> Load deterministic YAML fixtures through LocalCloud seed and reset endpoints.
>
> Source: https://local.cloud/docs/seed-data/

LocalCloud accepts YAML fixture data at root operator endpoints. Seeding covers the service registrars listed below; it is not a migration, backup, or production-data tool.

### Load and reload

```bash
curl -fsS -X POST http://localhost:5380/seed \
  -H 'Content-Type: application/yaml' \
  --data-binary @seed.yaml
```

The canonical gateway URL applies to manual Docker. With the host CLI, derive the actual gateway URL from `localcloud start`, `localcloud status`, or `localcloud env` because port `5380` can be remapped.

Other routes:

| Route | Behavior |
| --- | --- |
| `POST /seed` | Load a YAML body. |
| `POST /import` | Alias of `/seed`. |
| `POST /reseed` | Reload `LOCALCLOUD_SEED_FILE`, default `/opt/localcloud/seed.yaml`; replace default sample resources in the selected project, including changes inside them. |
| `POST /reset?project=...` | Clear one project; `{"restore_seed":true}` reapplies that project’s most recently loaded seed when available. |

### Accepted envelopes

#### Flat service keys

```yaml
# docs-example: seed-flat

gcs:
  buckets:
    - name: localcloud-docs-bucket
      objects:
        - key: fixtures/hello.txt
          content: Hello from LocalCloud

pubsub:
  topics:
    - name: docs-events
      subscriptions:
        - name: docs-events-sub
```

#### One-project `services` mapping

```yaml
# docs-example: seed-services

services:
  gcs:
    buckets:
      - name: localcloud-docs-bucket
  secretmanager:
    secrets:
      - name: docs-api-key
        versions:
          - data: fake-local-value
  bigquery:
    datasets:
      - name: analytics
        location: US
    tables:
      - dataset: analytics
        name: events
        schema:
          fields:
            - name: event_id
              type: STRING
              mode: REQUIRED
        rows:
          - event_id: event-001
```

BigQuery tables are top-level entries under `bigquery.tables`; every table names its dataset. Secret Manager records belong under `secretmanager.secrets`.

#### Multi-project mapping

```yaml
# docs-example: seed-projects

projects:
  local-gcp-project:
    services:
      gcs:
        buckets:
          - name: localcloud-main-project
  second-local-project:
    services:
      pubsub:
        topics:
          - name: second-project-events
```

### Supported seed registrars

The reviewed `SeedService` implementation registers `gcs`, `pubsub`, `bigquery`, `spanner`, `secretmanager`, `cloudtasks`, `memorystore`, `workflows`, `cloudscheduler` (alias `scheduler`), `cloudfunctions` (alias `functions`), `alloydb`, `dataproc`, `cloudiam` (alias `iam`), `cloudsql`, `bigtable`, `sheets`, `firestore`, and `kms`.

A registrar can still be unavailable if its service is disabled, its tier is unavailable, or its implementation was not registered in the assembled runtime. **Firestore has a seed registrar** and is disabled by default. Enable it explicitly and consult its operation contract. A registrar or successful fixture import does not establish complete query, listener, or recovery fidelity.

### Volatile restart mode

```bash
curl -fsS -X POST 'http://localhost:5380/seed?mode=volatile' \
  -H 'Content-Type: application/yaml' \
  --data-binary @seed.yaml
```

The current `VOLATILE_SEED_SERVICES` set is empty, so volatile mode selects no services. Pub/Sub now uses PostgreSQL persistence. Use normal explicit seeding for test-owned fixtures; retaining a volume is not a production durability guarantee.

### Startup file

Container startup and the Console own automatic samples. The CLI does not discover, mount, or apply seed files; `host.seed` is accepted but ignored. Set `server.auto_seed: false` to disable bootstrap samples. Manual Docker users can mount the seed and persistent data together:

```bash
docker volume create localcloud-data

docker run -d --name localcloud \
  -p 127.0.0.1:5380-5405:5380-5405 \
  -m 4g \
  -v "$PWD/seed.yaml:/opt/localcloud/seed.yaml:ro" \
  -v localcloud-data:/var/lib/localcloud \
  agentcloud/localcloud:latest
```

The `latest` image tag is mutable. Prefer `localcloud start`, and pin an image digest for release workflows.

### Terraform interaction

`LOCALCLOUD_TERRAFORM_MODE=true` causes seed requests to return a skipped result so Terraform-managed resources are not duplicated. Do not combine a Terraform resource-creation test with implicit startup seed data.

### Fixture safety

- Use stable IDs, deterministic values, and small datasets.
- Use fake secret payloads only; never copy production credentials or customer data.
- Assert the data through the same SDK/API path the application uses.
- Reset only the intended project and verify the response before continuing.
- Validate production migrations, backup/recovery, and secret handling separately against real Google Cloud.

---

## Architecture

> How LocalCloud works inside one container: the gateway, service processes, persistence, networking, and the settings operators control.
>
> Source: https://local.cloud/docs/architecture/

LocalCloud packages a Java gateway, the web console, local facades, and external emulator processes in one unified Docker container. “One container” does not mean every service shares the same protocol, process, storage engine, or compatibility level.

### Request flow

1. `localcloud start --local-only` selects a Docker data volume, discovers or creates one compatible runtime that listens only on localhost, and maps published canonical ports in the **5380–5405** range.
2. `localcloud env` resolves that runtime and returns environment variables and endpoint values for the selected project and caller.
3. SDK, REST, gRPC, and Terraform requests reach a direct emulator port or the gateway on canonical container port `5380` (HTTP) or `5381` (HTTPS / TLS).
4. The gateway handles operator routes and routes facade/API traffic to local implementations.

### Runtime identity and ownership

The named Docker volume mounted at `/var/lib/localcloud` is the only durable runtime selector; the default is `localcloud-data`. The CLI verifies the configured image and selects the unique compatible container using that volume. Immutable container ID is live process identity. A recorded ID is only a revalidated tie-break hint.

CLI-created container, network, and volume resources carry exact ownership labels. Ownership is independent per resource. The CLI can start, stop, restart, inspect, and use an attached compatible container, but it never removes or relabels a Docker resource it does not own. Ambiguous volume use, incompatible images, invalid labels, and shared-volume conflicts fail before mutation. `localcloud reset --all-projects` prints manual full-recreation steps and deletes nothing.

Root operator routes include `/health`, `/health/{service}`, `/readiness`, `/env`, `/services`, `/seed`, `/reseed`, `/import`, `/reset`, `/terraform/readiness`, `/graphql`, `/api-docs`, and `/docs`.

### Process and storage model

| Component | Current Implementation | Persistence Boundary |
| --- | --- | --- |
| **Gateway & Facades** | Java / Armeria services | Facade records use internal PostgreSQL beneath `/var/lib/localcloud/pgdata`; operation-specific limits apply. |
| **Cloud Storage** | `fake-gcs-server` process | Object blobs and bucket metadata stored beneath `/var/lib/localcloud/gcs-data`. |
| **Pub/Sub** | In-process Java facade | Topics, subscriptions, and queued messages use PostgreSQL under `/var/lib/localcloud/pgdata`. Delivery workers and connections restart; test exact replay and redelivery behavior. |
| **Firestore** | External emulator configuration | Documented local document/query workflows; opt-in. Test checkpoint, timestamp, listener, and transaction behavior with the exact image you run. |
| **Bigtable** | Custom emulator process | Backed by PostgreSQL under the mounted data root. Port `5385`. |
| **BigQuery** | Native GoogleSQL analysis + DuckDB execution | Supervised native in-container process; columnar DuckDB storage beneath `/var/lib/localcloud/bigquery-data`. Ports `5388` (REST) and `5389` (Storage Read gRPC with TLS). |
| **Spanner** | Extended Cloud Spanner emulator | LevelDB row data plus JSON metadata beneath `/var/lib/localcloud/spanner-data`. Ports `5386` (gRPC) and `5387` (REST). |
| **Memorystore** | Valkey-compatible process | Ports `5390` (plaintext) and `5394` (TLS). Check the documented RESP command and recovery subset. |
| **AlloyDB & Cloud SQL** | PostgreSQL 16 (`5391`) + companion MySQL 8.4 (`5406`) | Native PostgreSQL 16 data plane shared by Cloud SQL and AlloyDB; MySQL 8.4 hosted via companion container. |

A retained volume improves restart/container-replacement behavior only for stores that actually persist. It does not provide production replication, backups, disaster recovery, transaction parity, or durability guarantees.

### Canonical container ports

The host CLI may dynamically remap these ports if conflicts arise; generated endpoint output from `localcloud env` is authoritative for a running runtime.

LocalCloud organizes its network ports into clean, continuous tiers:

- **5380–5405**: In-container published range (`5380–5394` active services and TLS, `5395–5405` reserved buffer for future service additions).
- **5406 & 5443–5465**: External companion & child host processes (`5406` Cloud SQL MySQL companion container, `5443–5465` GKE k3d child clusters with `5443` as primary).
- **5410–5414**: Specialized & in-container loopback (`5410/udp` DNSmasq scoped DNS, `5411` Firestore private, `5412` BigQuery REST private, `5413` BigQuery Storage gRPC private, `5414` Supervisor XML-RPC private).

#### Published TCP Block (5380–5405)

| Port | Protocol / Transport | Purpose / Service | Active When |
| --- | --- | --- | --- |
| `5380` | HTTP/1.1 & HTTP/2 (REST/h2c) | Shared gateway, web console, operator APIs, MCP, and all in-process service facades | Server is ready |
| `5381` | HTTPS & HTTP/2 gRPC | Secure shared gateway (`tls.port`, default `5381`) | Global TLS enabled |
| `5382` | HTTP REST | Cloud Storage REST API (`fake-gcs-server`) | `gcs` enabled |
| `5383` | h2c gRPC | Cloud Pub/Sub direct SDK endpoint | `pubsub` enabled |
| `5384` | h2c gRPC / HTTP | Cloud Firestore wrapper | `firestore` enabled |
| `5385` | h2c gRPC | Cloud Bigtable (`little_bigtable`) | `bigtable` enabled |
| `5386` | h2c gRPC | Cloud Spanner data and admin APIs | `spanner` enabled |
| `5387` | HTTP REST / JSON | Cloud Spanner REST endpoint (**not PostgreSQL wire**) | `spanner` enabled |
| `5388` | HTTP REST / JSON | BigQuery query and metadata API | `bigquery` enabled |
| `5389` | HTTP/2 gRPC | BigQuery Storage Read/Write API (**TLS is always required**) | `bigquery` enabled |
| `5390` | RESP | Memorystore (Redis / Valkey plaintext) | `memorystore` enabled |
| `5391` | PostgreSQL wire protocol | Shared PostgreSQL data plane for Cloud SQL and AlloyDB (and LocalCloud metadata) | PostgreSQL is ready |
| `5392` | HTTPS REST | Cloud Storage TLS endpoint | Global TLS and `gcs` enabled |
| `5393` | HTTP/2 gRPC | Cloud Pub/Sub TLS endpoint | Global TLS and `pubsub` enabled |
| `5394` | RESP over TLS | Memorystore (Redis / Valkey TLS) | Global TLS and `memorystore` enabled |
| `5395–5405` | TCP | Reserved buffer for future in-container service additions | Reserved |

#### Shared Gateway Facades (Port 5380 / 5381)

All service control planes and in-process facades connect through the shared gateway on `5380` (HTTP/h2c) or `5381` (HTTPS/TLS) rather than individual dedicated ports. These include:

- **Security & Identity**: Cloud Secret Manager, Cloud KMS, Cloud IAM
- **Messaging & Integration**: Cloud Tasks, Cloud Scheduler, Cloud Workflows
- **Operations**: Cloud Logging, Cloud Monitoring, Cloud Resource Manager, Service Usage, Cloud Billing
- **Compute & Serverless**: Cloud Functions (2nd Gen), Cloud Run, Dataproc (control plane), GKE (control plane), Compute Engine
- **Databases**: Cloud SQL (control plane), AlloyDB (control plane)
- **Auxiliary Integration APIs**: Google Sheets

#### Companions and Subordinate Workloads

| Port | Protocol | Purpose / Service |
| --- | --- | --- |
| `5406` | MySQL wire protocol | Cloud SQL MySQL 8.4 companion container (`localcloud-mysql`) |
| `5410/udp` | DNS | Scoped `dnsmasq` resolver (mapped to host `53/udp` in transparent mode) |
| `5443–5465` | HTTPS (Kubernetes API) | GKE k3d child control-plane allocations (primary API server on `5443`) |

#### Internal Loopback Listeners (Never Published to Host)

| Listener | Purpose |
| --- | --- |
| `127.0.0.1:5411` | Private Firestore backend behind the public `5384` wrapper |
| `127.0.0.1:5412` | Private native BigQuery REST backend behind public `5388` proxy |
| `127.0.0.1:5413` | Private native BigQuery Storage backend behind public TLS `5389` proxy |
| `127.0.0.1:5414` | Supervisor XML-RPC control plane |

### Transparent networking and Docker socket

Transparent networking is disabled by default. Docker access defaults to `auto`; the socket is mounted when selected services declare that dependency. Set `host.docker_socket: false` to opt out. Unflagged CLI lifecycle commands publish ports on all host interfaces; the example above selects loopback explicitly.

- **Transparent networking** maps host `53/udp` to container `5410/udp`, host `80` to gateway `5380`, and host `443` to the configured native TLS port (`5381`). It requires scoped host DNS changes and certificate trust and is used only for clients that ignore custom endpoint variables.
- **Docker socket access** grants the container control over the host Docker daemon. It is required only for runtime workflows that deliberately create subordinate containers or clusters (such as Cloud SQL MySQL or GKE k3d). In-container BigQuery runs natively via Supervisord and does not require Docker socket access.

### Outbound behavior

LocalCloud is not categorically offline or zero-egress. Depending on configuration and feature use, the runtime can send telemetry, probe certificate storage, check image updates, validate licenses, validate live IAM bearer tokens, or dispatch scheduled/HTTP work. Core local workflows can continue offline after required images are present, but review [Privacy](https://local.cloud/docs/privacy/) and disable or isolate outbound features according to your environment.

### Production boundary

Local emulation does not reproduce Google Cloud IAM enforcement, quotas, managed networking, regional behavior, concurrency, performance, replication, or disaster recovery. Consult each service operation and support level, then run an explicit real-Google-Cloud validation before release.

---

## Web console

> Inspect and change local data from LocalCloud's built-in web console: service status, a data browser, BigQuery and Spanner query tools, and request logs.
>
> Source: https://local.cloud/docs/console/

Open the console for the selected runtime with the host CLI:

```bash
localcloud console
```

Trust the URL printed by the CLI because the gateway may be dynamically remapped from canonical port `5380`. Manual-Docker users on canonical ports can open `http://localhost:5380`.

### Dashboard and service status

The dashboard exposes runtime status, the selected project, request counts, and service health. Use `/health`, `/health/{service}`, `/readiness`, and `/services` for automation; the visual state is an operator aid rather than a production monitoring guarantee.

### Data browser

The Data Browser is **not read-only**. Depending on the selected service and current compatibility it can change data, including:

- creating buckets and folders;
- uploading and deleting Cloud Storage objects;
- creating and deleting Pub/Sub topics;
- publishing local Pub/Sub messages; and
- using service-specific mutation forms exposed by the runtime.

Treat console actions like API calls: use synthetic data, keep the selected project visible, and do not expose a permissive gateway outside loopback.

Read and query views include service-specific datasets, schemas, objects, documents, secret metadata, messages, keys, logs, and metrics. Availability follows enabled services and their compatibility evidence; not every Google Cloud console operation exists locally.

### SQL and service explorers

BigQuery and Spanner expose query and schema tooling for documented local workflows. Validate production SQL semantics separately.

The console also provides request logs and generated environment snippets. Generated values should be copied into the exact shell or process running local clients.

### Usage and cost estimates

Any displayed cost value is **indicative pricing only — not live Google Cloud rates**. It is not a bill, realized saving, or purchasing forecast. Pricing inputs and UI estimates can become stale; confirm the review date shown in the runtime and use current, authorized billing data for decisions.

### Security boundary

The console and many administrative paths are accessible even when IAM strict or `gcp-live` mode is enabled. Keep the runtime listening only on localhost. Docker access uses `auto` by default and can mount the host socket for selected services; set it to `false` to opt out. Transparent networking is a separate opt-in.

---

## Services overview

> Compare available LocalCloud services, startup defaults, connections, and known limitations.
>
> Source: https://local.cloud/docs/services-overview/

The runtime includes 27 service entries and publishes 27 guides. 25 entries have documented local integration workflows; unsupported and unknown entries remain in the catalog for reference. Google Sheets is an auxiliary fixture API, not a separate Google Cloud service. Availability does not mean full Google Cloud parity or that a service starts by default.

A service guide separates the facts that affect normal use:

1. **Starts by default** — whether `services.enabled: default` starts the service.
2. **Minimum tier** — Community, or [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier). The tier is a technical setting in the runtime; the license governs use.
3. **Status** — Supported (ready for local use) or Unsupported (cloud-only).
4. **Persistence** — whether data is volatile, metadata-only, service data, or stateless.
5. **Connection** — the canonical container port and protocol. Use `localcloud env` for the actual host endpoint.
6. **Known limits** — operations or Google Cloud behavior that LocalCloud does not provide.

| Service | Starts by default | Tier | Status | Persistence | Connection |
| --- | --- | --- | --- | --- | --- |
| [Firestore](https://local.cloud/services/firestore/) | no | Community | Supported | service-data | gRPC :5384 |
| [Bigtable](https://local.cloud/services/bigtable/) | yes | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) | Supported | service-data | gRPC :5385 |
| [Spanner](https://local.cloud/services/spanner/) | yes | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) | Supported | service-data | gRPC :5386 · HTTP/REST :5387 |
| [AlloyDB](https://local.cloud/services/alloydb/) | yes | Community | Supported | metadata | gRPC :5380 |
| [Memorystore (Redis/Valkey)](https://local.cloud/services/memorystore/) | yes | Community | Supported | service-data | RESP :5390 |
| [Cloud SQL](https://local.cloud/services/cloud-sql/) | yes | Community | Supported | service-data | HTTP/REST :5380 · PostgreSQL :5391 · MySQL :5406 |
| [Pub/Sub](https://local.cloud/services/pubsub/) | yes | Community | Supported | service-data | gRPC :5383 |
| [Cloud Tasks](https://local.cloud/services/cloud-tasks/) | yes | Community | Supported | service-data | gRPC :5380 |
| [Cloud Scheduler](https://local.cloud/services/cloud-scheduler/) | yes | Community | Supported | metadata | gRPC + HTTP/REST :5380 |
| [Cloud Workflows](https://local.cloud/services/cloud-workflows/) | yes | Community | Supported | metadata | gRPC :5380 |
| [Cloud Functions (2nd Gen)](https://local.cloud/services/cloud-functions/) | yes | Community | Supported | metadata | gRPC :5380 |
| [GKE](https://local.cloud/services/gke/) | no | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) | Supported | metadata | gRPC :5380 · k3d :5443 |
| [Compute Engine](https://local.cloud/services/compute-engine/) | no | — | Unsupported | metadata | HTTP/REST :5380 |
| [Cloud Run](https://local.cloud/services/cloud-run/) | no | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) | Supported | metadata | gRPC :5380 |
| [Vertex AI](https://local.cloud/services/vertex-ai/) | no | — | Unsupported | metadata | HTTP/REST :5380 |
| [Secret Manager](https://local.cloud/services/secret-manager/) | yes | Community | Supported | service-data | gRPC :5380 |
| [Cloud IAM](https://local.cloud/services/cloud-iam/) | yes | Community | Supported | metadata | gRPC :5380 |
| [Cloud KMS](https://local.cloud/services/cloud-kms/) | yes | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) | Supported | metadata | gRPC + HTTP/REST :5380 |
| [Cloud Resource Manager](https://local.cloud/services/cloud-resource-manager/) | yes | Community | Supported | metadata | HTTP/REST :5380 |
| [Service Usage](https://local.cloud/services/service-usage/) | yes | Community | Supported | stateless | HTTP/REST :5380 |
| [Cloud Billing](https://local.cloud/services/cloud-billing/) | yes | Community | Supported | metadata | HTTP/REST :5380 |
| [Cloud Logging](https://local.cloud/services/cloud-logging/) | yes | Community | Supported | metadata | gRPC :5380 |
| [Cloud Monitoring](https://local.cloud/services/cloud-monitoring/) | yes | Community | Supported | metadata | gRPC :5380 |
| [Cloud Storage](https://local.cloud/services/cloud-storage/) | yes | Community | Supported | service-data | HTTP/REST :5382 |
| [BigQuery](https://local.cloud/services/bigquery/) | yes | Community | Supported | service-data | HTTP/REST :5388 · gRPC :5389 |
| [Dataproc](https://local.cloud/services/dataproc/) | yes | Community | Supported | metadata | gRPC :5380 |
| [Google Sheets](https://local.cloud/services/google-sheets/) (Auxiliary API) | yes | Community | Supported | metadata | HTTP/REST :5380 |

### Categories

The [service catalog](https://local.cloud/services/) groups services by user goal, in this order: Databases, Messaging & Workflow, Compute & Runtime, Security, Operations, Storage, Analytics, and Auxiliary Integration APIs. The table above follows the same order. Implementation boundaries differ inside every category. Some are external emulator processes, some are local facades, and some require Docker-socket or transparent-network opt-ins.

### How to use the catalog

- Load the actual running endpoints with `localcloud env`; the host CLI may remap ports.
- Check the service detail and operation limitations before relying on a workflow.
- Keep the runtime listening only on localhost and use fake local data.
- Remove emulator variables and validate production behavior against real Google Cloud before release.

Open the [service catalog](https://local.cloud/services/) for all 27 guides or [Compatibility](https://local.cloud/compatibility/) for operation-level support and limitations.

---

## FAQ

> Verified answers about LocalCloud setup, compatibility, persistence, licensing, and troubleshooting.
>
> Source: https://local.cloud/docs/faq/

### General

#### What is LocalCloud?

LocalCloud is a local Google Cloud development sandbox. One Docker container runs local versions of Google Cloud services, a web console, and management APIs. Each service documents which operations it supports.

#### Is LocalCloud free?

Yes. During public preview, individuals and organizations, including for-profit companies, may use LocalCloud free of charge for local and internal development, testing, CI, evaluation, and internal pilots. No payment method or license key is required. Read the Licensing page and governing license for the exact terms.

#### What is the recommended setup?

Install the host CLI, verify Docker, start a persistent runtime, load its generated environment values, and open the returned console URL.

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud doctor
localcloud start --local-only
curl -fsS http://localhost:5380/readiness
eval "$(localcloud env)"
localcloud console
```

Start with --local-only so the runtime listens only on localhost. The CLI keeps data between restarts by default. If a default port is already in use, the CLI picks another one; use the URLs and environment values it returns.

### Compatibility

#### Do I need to change application code?

Some SDKs honor emulator variables without code changes; others require explicit endpoint or client configuration. Load localcloud env into the application process, check the operation matrix, and stop if a client falls back to real Google Cloud.

#### Which SDK languages are supported?

LocalCloud doesn't publish a per-language support matrix. Compatibility depends on client version, transport, endpoint handling, and emulator behavior; start from the SDK examples and validate your exact client and operation.

#### How complete is BigQuery emulation?

BigQuery runs on a DuckDB-backed local emulator; support is documented feature by feature.

#### Can I use LocalCloud in CI/CD?

Yes. The Public Preview License permits ongoing internal CI and delivery automation for individuals and organizations, including for-profit companies. Keep local CI credentialless and validate release behavior against real Google Cloud in a separate guarded step.

### Runtime behavior

#### How much memory does LocalCloud need?

The CLI allocates 4 GB by default. Actual use depends on enabled services and workload; LocalCloud isn't guaranteed to run with less.

#### How long does startup take?

Gate automation on localcloud start status plus /readiness (or the workflow-specific readiness endpoint), not a fixed duration. Startup time isn't benchmarked across platforms.

#### Is data persisted between restarts?

The CLI uses persistent storage by default. Pub/Sub uses PostgreSQL; other services use different stores and recovery limits. A mounted volume does not provide production durability, replication, or backup semantics.

#### How do I isolate or reuse a LocalCloud runtime?

The Docker volume mounted at /var/lib/localcloud identifies the runtime and keeps its data. Use --data-volume NAME on any runtime command for isolated storage. The CLI can attach to a compatible container already using that volume, but it never removes or relabels Docker resources it does not own.

```
localcloud start --local-only --data-volume payments-localcloud-data
localcloud status --data-volume payments-localcloud-data --verbose
```

#### Is LocalCloud fully offline?

Not entirely. Core local workflows can run offline after the required images are downloaded. Depending on configuration, the runtime can also emit telemetry, probe certificate storage, check image updates, validate licenses or live IAM tokens, and dispatch HTTP work; see the Privacy and Architecture guides for outbound behavior.

### Troubleshooting

#### What if a port is already in use?

Use the host CLI: if a default port is already in use, it picks another one. Then reload the generated environment values.

```
localcloud start --local-only
eval "$(localcloud env)"
```

Do not replace returned endpoint values with a hard-coded port.

#### What if a service is not responding?

Inspect the runtime and its logs. If you run the container manually on the default ports, /services shows service state.

```
localcloud status
localcloud logs --tail 50
curl -fsS http://localhost:5380/services
```

Confirm the service is enabled, its required tier is available, and its documented support level is suitable for the workflow.

#### Why do GKE, Cloud Run, and Dataproc need Docker access?

By default (host.docker\_socket: auto), the CLI mounts the Docker socket only when an enabled service needs it. Set host.docker\_socket: false to opt out. A read-write socket mount grants broad control of the host Docker daemon, so enable services that need it only when your workflow requires Docker containers or k3d.

Related policy and implementation details are documented in [Licensing](https://local.cloud/docs/licensing/), [Privacy](https://local.cloud/docs/privacy/), [Architecture](https://local.cloud/docs/architecture/), and the [service catalog](https://local.cloud/services/).

---

## Licensing

> LocalCloud's ongoing free-use policy for open-source projects, limited-time public preview terms, and compliance resources.
>
> Source: https://local.cloud/docs/licensing/

### Limited-time public preview

LocalCloud is free to use during the limited-time public preview under the **LocalCloud Public Preview License Agreement**.

> **Free public preview**
>
> Individuals and organizations, including for-profit companies, may use LocalCloud free of charge for development, testing, ongoing internal CI, and evaluation. No payment method or license key is required.

LocalCloud is designed as a local development and testing environment. Release behavior should be validated against real Google Cloud before deploying an application to production. The preview grant does not cover customer-facing production use, reselling LocalCloud, offering it as a hosted or managed service, redistribution, or sublicensing.

### Free for open-source projects

Under the **Free for open-source projects policy**, open-source contributors and maintainers can use LocalCloud free of charge for development, testing, and their project’s ongoing internal CI.

This policy is ongoing and independent of the limited-time public preview. Free use for open-source projects continues after the public preview ends.

Tests against local endpoints do not need a maintainer’s Google Cloud project, provision Google Cloud resources, or incur Google Cloud service charges. Your repository can include LocalCloud configuration, test launchers, and setup instructions that direct contributors to obtain the runtime themselves.

This policy establishes free use for open-source projects. The license supplied with each runtime release governs use and distribution of that release.

For a practical starting point, see [Bring No-Cost Cloud Integration Testing Into Your Repository: Low Setup, Easy Contributions](https://local.cloud/blog/localcloud-for-open-source/).

### Resources

For engineering, security, and procurement teams reviewing LocalCloud for organizational use:

- **Governing License Agreement**: The complete legal terms are published as the [LocalCloud Public Preview License Agreement](https://local.cloud/license/), with a [plain-text copy](https://local.cloud/license.txt). The full license text controls.
- **Website and Agent Skills repository**: This page summarizes runtime preview releases. The [website repository LICENSE](https://github.com/LocalGCloud/LocalGCloud.github.io/blob/main/LICENSE) currently contains a different, individual-only agreement. Consult the license supplied with the artifact you obtain; this summary does not change that repository’s terms.
- **Privacy and Outbound Data**: Detailed information regarding runtime telemetry, optional controls, and local data boundaries is documented in the [Privacy and Outbound Data Reference](https://local.cloud/docs/privacy/).
- **Runtime Components**: The LocalCloud runtime, including its [built-in MCP integration](https://local.cloud/glossary/mcp-server/) (accessible via the `/mcp` HTTP endpoint or the `localcloud mcp` stdio bridge), is covered under the same governing license.
- **Preview releases keep their terms**: Each version distributed under the Public Preview License remains available to its licensees under those terms. Later versions or services may be offered under different terms, but they do not retroactively alter the grant for preview releases already obtained under the agreement.

---

## Privacy

> How LocalCloud uses basic usage information and web analytics, how to turn off runtime telemetry and website analytics, and how to contact us.
>
> Source: https://local.cloud/docs/privacy/

Your local service data is stored in your LocalCloud runtime and configured storage. Connected tools and jobs you configure can send data elsewhere.

### Runtime reporting

We collect basic technical, usage, and diagnostic details to maintain LocalCloud and improve reliability. These include environment information, aggregate service and Console activity, service health, and errors. Reports use a pseudonymous identifier and are sent at startup and periodically while telemetry is enabled.

### Disable telemetry

Set this in the **LocalCloud container’s environment** before starting or recreating it:

```text
LOCALCLOUD_TELEMETRY=false
```

With Docker, add `-e LOCALCLOUD_TELEMETRY=false` to your `docker run` command. With Docker Compose, set it under the LocalCloud service’s `environment` section.

**This stops regular runtime and Console reporting.** When a reporting key is configured, one startup event still records that telemetry is disabled.

Update checks, license validation where enforced, live-cloud authentication, and jobs or feedback you choose to send can still make network requests.

### Website analytics

We use basic web analytics to understand visits, usage, and performance. Analytics providers collect the browser, device, network, and interaction details needed to provide these services. Search text and feedback you submit may also be recorded to improve the documentation.

PostHog also collects dead clicks (clicks with no visible response) to help us find usability problems. On desktop-sized viewports, it collects heatmaps and sampled session recordings. On mobile-sized viewports, recordings and heatmaps are disabled; page visits, clicks, searches, copy actions, and errors remain enabled. Input values are masked in recordings. Console logs, network request and response contents, and canvas recording are disabled.

We collect sampled browser performance measurements to find slow pages and interactions. Reports include the website release so we can identify regressions after changes.

When someone downloads the install script from `local.cloud/install.sh`, the site’s Cloudflare Worker sends PostHog one `install_script_fetched` event with a random one-time identifier, the downloading tool (curl, wget, or other), the country Cloudflare derives from the request, and, when the download was linked from a local.cloud page, that page’s path. It does not send the IP address or create a person profile.

Please do not include secrets, credentials, personal data, or customer data in search or feedback fields. The runtime telemetry setting does not control website analytics.

#### Turn website analytics off

Every page has an **Analytics: On** control at the bottom of the footer. Select it to switch to **Analytics: Off**: the site then stops PostHog capture and session recording and no longer loads the PostHog or Cloudflare Web Analytics scripts in that browser, so it records no page views, searches, copies, clicks, or heatmaps from it. The choice is stored in your browser until you switch it back or clear site data.

If your browser sends a Global Privacy Control or Do Not Track signal, the site treats analytics as off without any action from you, and the footer control shows **Analytics: Off** with the signal’s name. The install script event above is counted by the server when the script is downloaded, so this browser setting does not apply to it.

### Contact

For privacy questions or deletion requests, email [info@local.cloud](mailto:info@local.cloud?subject=Privacy%20request). Other ways to reach us are on the [contact page](https://local.cloud/contact/).

---

## BigQuery emulator feature reference

> Run BigQuery locally with native GoogleSQL and DuckDB: endpoints, documented operations, the coverage matrix and limits of LocalCloud's BigQuery service.
>
> Source: https://local.cloud/docs/bigquery-emulator-features/

The current LocalCloud source packages a native **GoogleSQL Analyzer** and **DuckDB** query engine. Supervisord manages the BigQuery process inside the LocalCloud Docker container. Running LocalCloud requires Docker; the default BigQuery process does not need a Docker-socket mount. An optional custom BigQuery image uses a companion container and requires Docker access.

> **Test the image you run**
>
> The operation table describes the current source contract. The `latest` image tag is mutable, so pin an image digest when repeatability matters and test the exact image and client you use; source-level implementation and a finite query benchmark do not establish complete semantic parity.

### Connection and endpoints

| Surface | Canonical endpoint | Boundary |
| --- | --- | --- |
| REST API | `http://localhost:5388` | BigQuery dataset, table, job, and query routes. |
| Storage API | `localhost:5389` | Separate gRPC listener with TLS; configure the Storage client and trust the LocalCloud CA. |
| Environment export | `BIGQUERY_EMULATOR_HOST=http://localhost:5388` | Use the actual value from `localcloud env`; some SDKs need explicit client options. |
| Gateway proxy | `http://localhost:5380/bigquery/v2/` | Gateway authentication and routing differ from direct listeners. |
| Persistence | `/var/lib/localcloud/bigquery-data` | DuckDB and metadata beneath the mounted LocalCloud data volume. |

The CLI may remap host ports. The [Python SDK example](https://local.cloud/docs/sdk-examples/#bigquery-deterministic-query) passes the generated REST endpoint explicitly and uses anonymous credentials. A REST client configuration does not configure the Storage API client.

### Current operation contract

| Operation area | Status | Boundary |
| --- | --- | --- |
| datasets.create/list/update/delete | Supported |  |
| tables.create/list/update/delete | Supported | Table creation, metadata updates, deletion, table clones with time travel (FOR SYSTEM\_TIME AS OF), table copies, temp tables, wildcard tables, row-level access policies, policy tags, and data masking. |
| jobs.query/cancel/delete/serviceAccount/projects | Supported | Job execution, cancellation, deletion, serviceAccount lookup, dry runs with byte estimates, project listing, scheduled queries, reservation routing, and BigQuery ML model training/evaluation lifecycle. |
| SELECT, JOIN, window functions, CTEs, PIVOT/UNPIVOT, MERGE | Supported | Query coverage varies by capability and input. Review the dependency coverage matrix, and test semantics and errors with your application queries. |
| DECLARE, SET, IF/WHILE/LOOP/REPEAT/FOR, BEGIN/EXCEPTION, CALL, EXECUTE IMMEDIATE | Supported | Full procedural language support with variable declaration, flow-of-control, exception handling, dynamic SQL (EXECUTE IMMEDIATE with USING/INTO), and stored procedures (CREATE PROCEDURE / CALL). |
| CREATE MATERIALIZED VIEW, auto-refresh | Supported | CREATE MATERIALIZED VIEW with PARTITION BY, CLUSTER BY, OPTIONS, always-fresh reads, and automated refresh procedure. |
| query Parquet/CSV/JSON/Avro/ORC files (local + GCS) | Supported | External tables and load jobs over emulated gs:// (CSV with BigQuery header autodetect, JSONL, Parquet, Avro, ORC with schema autodetect and hive partitions). EXTERNAL\_QUERY over SQLite, PostgreSQL, and MySQL. |
| gRPC Storage Read/Write API (AVRO + Arrow) | Supported | gRPC endpoint on port 5389. ReadRows with streaming support; AppendRows Storage Write API. Spark Storage Read connector verified 11/11 cases across client profiles. |
| INFORMATION\_SCHEMA views | Supported | Full catalog coverage including COLUMNS, TABLES, SCHEMATA, PARTITIONS, VIEWS, ROUTINES, ROUTINE\_OPTIONS, PARAMETERS, COLUMN\_FIELD\_PATHS, TABLE\_OPTIONS, TABLE\_STORAGE, OBJECT\_PRIVILEGES, MATERIALIZED\_VIEWS, JOBS\_BY\_\*, SESSIONS\_BY\_\*, RESERVATIONS, and search/vector index views. |

### Feature areas to test

- **GoogleSQL execution:** test the exact types, expressions, joins, scripting, and error behavior used by the application.
- **BQML:** selected local models are implemented; model types, feature shapes, and `TRANSFORM` variants have documented gaps.
- **Vector Search and text search:** check the specific index, function, and option against the feature inventory.
- **Geography:** spherical functions have bounded geometry and input support, including remaining snapping, covering, and union gaps.
- **Security and governance:** row policies, masking, and IAM-shaped APIs require path-specific tests. Nested policy tags and taxonomy operations have recorded boundaries.
- **External tables and federation:** validate the exact source format and connector. An emulator fixture or stored connection does not prove a live federated query.
- **Storage API and Spark:** test transport, TLS, schema, read/write method, connector version, and architecture separately.

To weigh LocalCloud against standalone emulators and real BigQuery, see [BigQuery emulator alternatives](https://local.cloud/compare/bigquery-emulator-alternatives/).

### Coverage matrix

The BigQuery emulator keeps a versioned coverage matrix. It includes canonical and derived records, so its total is a count of records, not a count of distinct canonical GoogleSQL capabilities or executed tests.

> **Recorded source coverage**
>
> These counts are the dependency’s recorded classifications. Test the features your application depends on with the LocalCloud image you run. Unknown records are unassessed. Unsupported records include local feature gaps as well as managed-cloud behavior.

| Dimension | Implemented | Implemented with limits | Unsupported | Unknown | Total records |
| --- | --- | --- | --- | --- | --- |
| Development | 1067 | 12 | 73 | 385 | 1537 |
| Production parity | 1067 | 12 | 73 | 385 | 1537 |

“Implemented” is a matrix classification tied to the emulator’s implementation and test references; test the exact feature, input shape, and client your application uses. “Implemented with limits” rows work locally within the concrete boundaries listed below; derived rows can overlap their child features.

#### Capabilities implemented with documented limits

The matrix records 12 development capabilities that work locally within documented limits. Each row names the capability and the boundary recorded for it.

| Capability | Recorded boundary |
| --- | --- |
| **PARTITION BY** `sql.ddl.partition-by` | Ingestion-time partitioning (PARTITION BY \_PARTITIONDATE/\_PARTITIONTIME) and the \_PARTITIONTIME/\_PARTITIONDATE pseudocolumns are not supported: the pinned analyzer rejects the pseudocolumns in DDL |
| **CREATE MODEL (BQML)** `sql.ddl.create-model-bqml` | STRUCT and non-numeric ARRAY features, TRANSFORM for PCA/DNN/autoencoder/time-series/matrix-factorization/contribution models, DNN\_LINEAR\_COMBINED\_\*, and TensorFlow/AutoML model types are refused locally |
| **ST\_SNAPTOGRID** `sql.function.st-snaptogrid` | Only points and empty values are snapped; lines, polygons and multi-part values need S2Builder IntLatLngSnapFunction, which the installed S2 bindings do not expose |
| **CREATE MODEL** `metadata.enterprise.create-model` | STRUCT and non-numeric ARRAY features, TRANSFORM for PCA/DNN/autoencoder/time-series/matrix-factorization/contribution models, DNN\_LINEAR\_COMBINED\_\*, and TensorFlow/AutoML model types are refused locally |
| **Column-level security** `metadata.enterprise.column-level-security` | Policy tags on nested RECORD fields are refused; taxonomy import/export and cross-location replication are not served |
| **Cloud Storage (CSV, JSON, Avro, Parquet, ORC, Bigtable)** `metadata.advanced.cloud-storage-csv-json-avro-parquet-orc-bigtable` | Bigtable external tables are not implemented; Google Sheets, HTTP(S) and local-file sources are also outside the native external-table path (see the child rows) |
| **Column-level security (policy tags)** `metadata.advanced.column-level-security-policy-tags` | Policy tags on nested RECORD fields are refused; taxonomy import/export and cross-location replication are not served |
| **ML.TRANSFORM** `metadata.advanced.ml-transform` | TRANSFORM works for linear/logistic regression, KMEANS, boosted trees, random forests and TRANSFORM\_ONLY; \* REPLACE, expression.\*, named preprocessing arguments and WARM\_START are refused |
| **Spark BigQuery connector Storage Read data path** `client.spark.spark-bigquery-connector-storage-read` | Production Storage Read IAM is not emulated. Managed service scale and global availability are outside the pinned client profile. |
| **TRANSFORM** `sql.ddl.transform` | TRANSFORM works for linear/logistic regression, KMEANS, boosted trees, random forests and TRANSFORM\_ONLY; \* REPLACE, expression.\*, named preprocessing arguments and WARM\_START are refused |
| **S2\_COVERINGCELLIDS** `sql.function.s2-coveringcellids` | Multi-point, multi-linestring and mixed collections, and buffers on non-point values, are refused |
| **ST\_UNION\_AGG** `sql.function.st-union-agg` | Linestring inputs (BigQuery merges them into one LINESTRING) and mixed point/polygon results are refused |

#### Unsupported and unknown records

Before relying on a capability that this page does not list, test it with your application’s queries. Unsupported and unknown states must not be reduced to cloud scale alone: syntax, model variants, external sources, collation, and individual API methods can have developer-visible gaps. A successful dry run, stored configuration, or metadata operation does not prove execution support.

#### How to check a capability

1. Check the required capability ID and its exact operation and input boundary.
2. Confirm the dependency identity used by the LocalCloud image; dependency HEAD can differ from a packaged payload.
3. Run the application’s query or API workflow, assert the result and errors, and test restart when persistent state matters.
4. Record client versions, platform, dependency revision, assembled-image digest, failures, and skips.
5. Validate required production behavior against Google Cloud using a separate environment.

### Runtime and production boundaries

- Coverage records describe the emulator source; validate the semantics your application depends on.
- Ingestion-time partitioning (PARTITION BY \_PARTITIONDATE/\_PARTITIONTIME) and the \_PARTITIONTIME/\_PARTITIONDATE pseudocolumns are not supported: the pinned analyzer rejects the pseudocolumns in DDL
- STRUCT and non-numeric ARRAY features, TRANSFORM for PCA/DNN/autoencoder/time-series/matrix-factorization/contribution models, DNN\_LINEAR\_COMBINED\_\*, and TensorFlow/AutoML model types are refused locally
- Only points and empty values are snapped; lines, polygons and multi-part values need S2Builder IntLatLngSnapFunction, which the installed S2 bindings do not expose
- Policy tags on nested RECORD fields are refused; taxonomy import/export and cross-location replication are not served
- Bigtable external tables are not implemented; Google Sheets, HTTP(S) and local-file sources are also outside the native external-table path (see the child rows)
- TRANSFORM works for linear/logistic regression, KMEANS, boosted trees, random forests and TRANSFORM\_ONLY; \* REPLACE, expression.\*, named preprocessing arguments and WARM\_START are refused
- Production Storage Read IAM is not emulated. Managed service scale and global availability are outside the pinned client profile.
- Multi-point, multi-linestring and mixed collections, and buffers on non-point values, are refused
- Linestring inputs (BigQuery merges them into one LINESTRING) and mixed point/polygon results are refused
- Google-managed reservations, fleet scale, replication, and IAM integrations require production validation.
- Survives restart with the LocalCloud volume

Validate required production IAM, billing, quotas, reservations, concurrency, managed integrations, and recovery in Google Cloud. Local functional gaps also need validation; they are not all cloud-only infrastructure limitations.

---

## Bigtable emulator feature reference

> Run Bigtable locally with LocalCloud: supported operations, PostgreSQL-backed persistence, and SQL support for development and tests.
>
> Source: https://local.cloud/docs/bigtable-emulator-features/

LocalCloud runs a separately maintained Bigtable emulator for row and administration APIs. The current Docker build pins a source commit.

> **Test the paths you need**
>
> The runtime contract records each operation’s concrete boundaries. The `latest` image tag is mutable; confirm the packaged dependency version and test the exact row, administration, and recovery paths you need.

### Connection and persistence

| Surface | Canonical value | Boundary |
| --- | --- | --- |
| Primary API | gRPC on `localhost:5385` | Use `BIGTABLE_EMULATOR_HOST` from `localcloud env` for actual mapped ports. |
| Backing store | PostgreSQL under the mounted LocalCloud volume | A standalone dependency’s SQLite configuration is not the LocalCloud default. |
| Console SQL | LocalCloud SQL-to-row-API translator | Separate from native GoogleSQL `PrepareQuery` / `ExecuteQuery` and session protocols. |

### Current operation contract

| Operation area | Status | Boundary |
| --- | --- | --- |
| instances/tables/families | Supported | The pinned little\_bigtable v0.5.0 emulates instance, cluster, app-profile, table and schema-bundle administration as validated metadata (ID and field rules, response views, update masks, pagination, deletion protection, soft delete and 7-day undelete, atomic column-family changes, initial splits, row key schema) with a durable long-running-operation registry. Cluster nodes and autoscaling settings are stored without capacity effects. Dependency conformance tests pass. |
| row mutations and reads | Supported | The emulator validates every mutation before applying any (single-row atomicity), reports real per-entry MutateRows codes, honors idempotency tokens and aggregate (Sum/Min/Max, HLL++) families, implements every RowFilter including Interleave duplicates, Sink (cells bypass subsequent filters; invalid inside Condition) and ValueBitmask, chunks ReadRows like production with request stats, samples SampleRowKeys within row ranges, enforces authorized-view, materialized-view and app-profile targets, and serves the OpenTable/OpenAuthorizedView/OpenMaterializedView session protocol. last\_scanned\_row\_key is not emitted. Sink output and rejection inside Condition have named dependency conformance tests; validate Sink filters in your own test suite. Dependency conformance tests pass. |
| cbt CLI compatibility | Supported | The \`cbt\` CLI works with BIGTABLE\_EMULATOR\_HOST env var. Arbitrary project and instance IDs are accepted on-demand without pre-registration, matching Google Cloud SDK CBT emulator behavior. The gRPC data plane accepts requests without an authorization header or credential provider. Instance CRUD (create/list/get/delete instance) is supported via gRPC. Table and row operations work as expected. The pinned cbt conformance test was skipped because cbt was not installed; validate cbt scripts in your own test suite. |
| localcloud console data browser | Supported | REST endpoints for instance/table/row CRUD exposed via BigtableAdminService: - GET /.../tables/{table}/rows — browse rows - POST /.../tables/{table}/rows — write cells - DELETE /.../tables/{table}/rows/{rowKey} — delete row SDK and console share the same PostgreSQL-backed emulator state. Instance, table and backup routes forward to the emulator and return its errors with the Google API HTTP mapping (FAILED\_PRECONDITION as 400, for example). Row writes and deletes, app-profile and view routes still ignore emulator errors and report success from local placeholder state, and instance PATCH/PUT and table PATCH answer locally without reaching the emulator, so a rejected request on those routes can appear to succeed. |
| data survives emulator restart | Supported | The emulator persists all resource state in PostgreSQL, including table policy fields, views, schema bundles, backups and their row snapshots, IAM policies, long-running operations, the change-stream outbox and idempotency tokens. On first start it migrates table metadata in place (one-way). Its restart tests ran on SQLite; validate PostgreSQL restart durability in your own test suite. |
| materialized views (CMVs) | Supported | The emulator implements continuous materialized views from GoogleSQL GROUP BY or ORDER BY definitions over existing tables. Views are read-only, read through materialized\_view\_name (ReadRows, SampleRowKeys, sessions) or GoogleSQL, recomputed before a read when stale, limited to 50 per instance and 5 per source table, and their query is immutable. Multi-column row-key encoding is emulator-specific. |
| GoogleSQL queries and logical views | Supported | The emulator builds its GoogleSQL engine by default. PrepareQuery returns a prepared-query token valid for one hour; ExecuteQuery streams typed ProtoRows batches with CRC32C checksums and resume tokens, and returns FailedPrecondition (PREPARED\_QUERY\_EXPIRED) after a schema change. Logical-view queries are validated against existing tables and are queryable. Query statistics and view parameters are not emulated. The Console SQL editor uses LocalCloud's separate translator. |
| change streams | Supported | The emulator records changes only for tables with change\_stream\_config (1-7 day retention). ReadChangeStream returns one grouped record per row commit, garbage-collection and DropRowRange records, heartbeats with continuation tokens and low watermarks, resumes from tokens and closes at end\_time. It requires a single-cluster app profile. One partition covers the whole key space, so partition split and merge are not exercised. |
| snapshots and backups | Supported | Backups are immutable schema-and-row snapshots with create, get, list (filter, order, pagination), update, copy, delete and restore to a new table independent of the live source, including expire-time, backup-type and quota rules. UndeleteTable restores a deleted table within 7 days. Legacy table snapshot RPCs return Unimplemented because they are a deprecated private-alpha API. The LocalCloud REST facade forwards backup create, get, list, update (with the required updateMask), copy, delete, restore and undelete to the emulator and returns its errors. |
| IAM policy management | Supported | The emulator persists policies on existing Bigtable resources with etags (Aborted on mismatch) and update masks, and returns NotFound for missing resources. Policies are permissive. TestIamPermissions grants every requested permission and nothing is enforced on the direct gRPC listener, because the emulator is unauthenticated. |
| new proto methods return Unimplemented (no panics) | Supported | The executable ledger dispositions all 89 registered RPCs of the cloud.google.com/go/bigtable v1.58.0 interface, and a test fails if one is missing. Intentionally unsupported RPCs (legacy snapshots, hot tablets, memory layers) return Unimplemented instead of panicking. PingAndWarm validates the instance name and app profile. |

### Runtime and recovery limits

- The pinned little\_bigtable v0.5.0 passes its dependency test suite, and its executable ledger covers all 89 registered RPCs. Those tests cover the dependency source, not the LocalCloud image. It ran on SQLite rather than LocalCloud's PostgreSQL backend and skipped the pinned cbt test. Confirm project deletion and backup listing through the native admin API. The LocalCloud fixes for both pass BigtablePlatformTest with a source JAR over that image.
- IAM policies persist but are not enforced. TestIamPermissions grants every requested permission because the emulator is unauthenticated; the direct gRPC listener also bypasses gateway IAM.
- Change streams use one partition with no split or merge. last\_scanned\_row\_key is not emitted, logical views do not support view parameters, query statistics are not recorded, and google.cloud.location.Locations is not served.
- HLL++ aggregate sketch bytes and multi-column materialized-view row keys use emulator-specific encodings that are not byte-compatible with production.
- Legacy table snapshot RPCs (SnapshotTable, GetSnapshot, ListSnapshots, DeleteSnapshot, CreateTableFromSnapshot) return Unimplemented; they are a deprecated private-alpha API. Use backups for data protection.
- The Console REST admin facade ignores emulator errors on row writes and deletes and on app-profile and view routes, then reports success from local placeholder state. Instance PATCH/PUT and table PATCH answer locally without reaching the emulator, and logical and materialized view updates drop their update masks. Verify through the native API when a result must reflect emulator validation.
- LocalCloud Docker is intended to retain PostgreSQL-backed service data while the mounted /var/lib/localcloud volume is retained
- The machine-local cached artifact can use PostgreSQL or SQLite, but the LocalCloud Docker product is configured for PostgreSQL.
- Test restart recovery with the exact LocalCloud image you run.

Metadata-only backup, view, or IAM operations do not prove data restoration, query execution, or authorization enforcement. Assert exact row bytes through the application data client and test required connector behavior separately. Validate production-managed behavior in Google Cloud.

---

## LocalCloud MCP for AI coding agents

> Give AI coding agents a free local cloud environment to build, test, and debug Google Cloud applications through MCP.
>
> Source: https://local.cloud/docs/mcp/

LocalCloud gives your coding agent a free local cloud environment for building, testing, and debugging Google Cloud applications. Through MCP, the agent can discover local services, obtain SDK configuration, inspect resources, query data, and diagnose application failures. Your application uses standard Google Cloud SDKs pointed at the local runtime.

The MCP bridge is included in **LocalCloud CLI 0.1.9 and newer**. Docker runs the cloud environment on your machine; a live Google Cloud project is not required for these local workflows.

### Install and connect

On macOS, or Linux with Homebrew:

```sh
brew install LocalGCloud/tap/localcloud
lc --version
lc doctor
lc mcp install --client cursor
```

For an existing Homebrew installation, run `brew update` and `brew upgrade localcloud`. Confirm that `lc --version` reports **0.1.9 or newer**.

On macOS or Linux without Homebrew:

```sh
curl -fsSL https://local.cloud/install.sh | sh
localcloud --version
localcloud doctor
localcloud mcp install --client cursor
```

Reload Cursor, enable the `localcloud` MCP server, and let it connect. The bridge starts or reuses the runtime automatically. The first connection can take longer while the runtime image downloads. To finish that download and deliberately bind newly started runtime ports to localhost first, run:

```sh
lc start --local-only
```

The [signed CLI releases](https://github.com/LocalGCloud/localcloud-cli/releases) include macOS ARM64/x86\_64 and Linux ARM64/x86\_64 binaries. macOS binaries require macOS 13 or newer; Linux binaries require glibc 2.35 or newer. Native Windows binaries are not shipped; Windows users need a suitable Linux/WSL environment and matching client configuration.

#### Runtime version and existing environments

Use **runtime 0.1.5 or newer** for validated strict-client tool input and output schemas. CLI and runtime versions are independent; connecting MCP or updating the CLI reuses an existing container.

Inspect `lc status`. To deliberately upgrade the selected runtime while retaining its named data volume:

```sh
lc restart --image agentcloud/localcloud:0.1.5 --pull
```

Use the same `--data-volume` and configuration file if you normally target a custom environment. The restart briefly interrupts clients; reconnect afterward.

Clients supporting desktop extensions can also install the [LocalCloud MCP 0.1.9 bundle](https://github.com/LocalGCloud/localcloud-cli/releases/download/v0.1.9/localcloud-mcp-0.1.9.mcpb). The bundle includes the supported-platform CLI; Docker and runtime 0.1.5+ are still required.

### Choose your coding client

| Client | Setup |
| --- | --- |
| Cursor | `lc mcp install --client cursor` |
| Claude Code | `lc mcp install --client claude-code` |
| Claude Desktop | `lc mcp install --client claude-desktop` |
| Windsurf | `lc mcp install --client windsurf` |
| Antigravity | `lc mcp install --client antigravity` |
| Codex | `codex mcp add localcloud -- "$(command -v localcloud)" mcp` |
| VS Code / GitHub Copilot | Add the stdio server to `.vscode/mcp.json`, as shown below |
| Cline | Add the server through Cline’s MCP settings editor |
| Gemini CLI | `gemini mcp add --scope user localcloud "$(command -v localcloud)" mcp` |

CLI 0.1.9’s `--client gemini` alias targets Antigravity, not Gemini CLI. Its `--client all` option writes the Cursor, Claude Code, Claude Desktop, Antigravity, and Windsurf configurations; use the manual instructions for Cline and Gemini CLI.

For desktop applications, use the absolute executable path from `command -v localcloud`. `/opt/homebrew/bin/localcloud` below is an Apple Silicon Homebrew example. Merge the entry into your client’s existing configuration so other MCP servers are preserved.

#### Cursor, Claude Desktop, and Cline

For a client that uses the `mcpServers` format:

```json
{
  "mcpServers": {
    "localcloud": {
      "command": "/opt/homebrew/bin/localcloud",
      "args": ["mcp"]
    }
  }
}
```

Use Cline’s configuration editor rather than assuming an extension settings-file location.

#### VS Code

VS Code uses `servers` in `.vscode/mcp.json`:

```json
{
  "servers": {
    "localcloud": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/localcloud",
      "args": ["mcp"]
    }
  }
}
```

Run **MCP: List Servers** in the Command Palette, then start `localcloud`.

### Give your agent its first task

![A coding agent connects through LocalCloud MCP, while its integration tests use standard SDKs with discovered local endpoints.](https://local.cloud/brand/localcloud-mcp-flow.svg)

Copy this prompt into your coding client:

> Use the LocalCloud MCP server. List local services, check readiness, and obtain the SDK environment for this project. Check compatibility before writing a small integration test. Use only the returned local endpoints. Stop if the required operation is unavailable; do not request real Google Cloud credentials or fall back to real Google Cloud.

The first calls are `localcloud_list_services` with `{}`, followed by readiness and `localcloud_get_env` with `{"format":"json"}`. Generated endpoint values account for the running runtime’s port mappings.

| Task | Agent workflow |
| --- | --- |
| Build a storage and messaging feature | Discover Cloud Storage and Pub/Sub, configure the SDKs, upload a test object, publish a message, and verify the result |
| Explore local data | Browse datasets and tables, inspect database connection profiles, and run a supported query |
| Write an integration test | Read compatibility, create only test-owned resources, assert results, and clean up through the SDK |
| Debug a failure | Inspect readiness, logs, recent requests, endpoint configuration, and API schemas, then rerun the failing test |

Run the [MCP walkthrough and three cloud workflows](https://local.cloud/blog/localcloud-mcp-agent-cloud/), or use the [SDK examples](https://local.cloud/docs/sdk-examples/) and [Terraform guide](https://local.cloud/docs/terraform/). Agents can also read the [agent entry point](https://local.cloud/ai/agents.md) and the [machine-readable installation guide](https://github.com/LocalGCloud/localcloud-cli/blob/main/llms-install.md).

### Services, tools, resources, and prompts

The runtime provides service and project inspection, a catalog of local management API operations, resource browsing, supported data queries, SDK/gcloud/Terraform configuration, compatibility checks, diagnostics, recipes, and test prompts.

Read the connected runtime’s `tools/list`, `resources/list`, `resources/templates/list`, and `prompts/list` results for its actual catalog. CLI versions and runtime versions are independent. Use `localcloud_get_api_catalog` before `localcloud_call_api` rather than guessing management routes.

The default data volume is shared across clients and repositories. `--project-id` selects a logical project; choose a separate `--data-volume` when you need an independent runtime. SDK operations can change local data, so tests should use their own resources and explicit cleanup.

Write and destructive MCP management operations depend on the runtime settings `LOCALCLOUD_MCP_WRITE` and `LOCALCLOUD_MCP_DESTRUCTIVE`, both disabled by default. Installing a client configuration does not enable those privileges. Local compatibility is service- and operation-specific; validate application release behavior against Google Cloud separately.

### Troubleshooting

| Symptom | Next step |
| --- | --- |
| `mcp install` is unavailable | Update to CLI 0.1.9+ and confirm the client launches the updated executable |
| Client rejects a tool schema or structured result | Check the running runtime version; use 0.1.5+ and reconnect after an explicit upgrade |
| Docker is unavailable | Run `lc doctor`, start Docker, and reconnect |
| Client cannot find the command | Use the absolute path reported by `command -v localcloud` |
| First connection times out | Run `lc start --local-only` once, then reconnect; increase the client’s startup timeout if needed |
| Runtime connection fails | Inspect `lc status` and `lc logs --tail 100`; try bridge argument `--connect-timeout 60` |
| Write operation is rejected | Check its safety classification and runtime permissions; do not assume installation enabled writes |
| A tool or service is missing | Check the runtime image/version, discovered catalog, readiness, and compatibility |

The [full MCP reference](https://github.com/LocalGCloud/localcloud-cli/blob/main/docs/mcp.md) covers bridge architecture, flags, caller/project context, resources, and prompts. Review [licensing](https://local.cloud/docs/licensing/) and [privacy](https://local.cloud/docs/privacy/) for the artifact you install. For a problem report, include the CLI version, runtime image, client name, and sanitized error output in a [CLI issue](https://github.com/LocalGCloud/localcloud-cli/issues).

---

## Spanner emulator feature reference

> Run Spanner locally with LocalCloud: GoogleSQL and PostgreSQL dialects, gRPC and REST endpoints, persistence, and per-operation limits.
>
> Source: https://local.cloud/docs/spanner-emulator-features/

LocalCloud integrates an extended Cloud Spanner emulator. GoogleSQL and PostgreSQL dialects run through the Spanner API; dialect support does not imply complete SQL, transaction, graph, search, authorization, backup, or change-stream parity.

> **Use the operation boundaries**
>
> The table below retains the runtime’s recorded operation boundaries and limitations. Standalone dependency tests don’t cover the LocalCloud image. Validate the exact client, operation, dialect, and image used by the application.

### Connections and persistence

| Surface | Canonical value | Boundary |
| --- | --- | --- |
| gRPC API | `SPANNER_EMULATOR_HOST=localhost:5386` | Use generated host ports and test the selected SDK/version. |
| REST gateway | `http://localhost:5387` | REST / grpc-gateway, not PostgreSQL wire. |
| PostgreSQL dialect | Queries through the Spanner API | LocalCloud does not package PGAdapter; `psql` and pgJDBC need a separately configured adapter. |
| State | LevelDB rows and JSON metadata under `/var/lib/localcloud/spanner-data` | Mounted storage is required for retained state; see the recovery limits below. |

Use `localcloud env` for the actual mapped endpoints. Provision the instance, database, and schema before querying; a code example that refers to an uncreated database is not a complete quick start.

### Current operation contract

| Operation area | Status | Boundary |
| --- | --- | --- |
| Native SQL, read, and streaming read | Supported | Native ExecuteSql and ExecuteStreamingSql in both GoogleSQL and PostgreSQL dialects. StreamingRead and ExecuteStreamingSql stream whole rows with resume tokens at row boundaries. Unary ExecuteSql intentionally retains the emulator's rejection of change-stream queries. Full-text search (TOKENIZE\_\*, SEARCH, SNIPPET, SCORE), vector search (APPROX\_\* / ScaNN), and 13 graph algorithms (PageRank, ShortestPath, etc.) compute locally. |
| Sessions, transactions, and batch DML | Supported | Sessions (including batch create and multiplexed), read-write, read-only and single-use transactions. SERIALIZABLE (default) and REPEATABLE\_READ isolation. Conflicts follow wound-wait lock waits (--lock\_wait\_timeout\_ms). Exclusive locks via SELECT ... FOR UPDATE and LOCK\_SCANNED\_RANGES=exclusive. Commit timestamps (PENDING\_COMMIT\_TIMESTAMP) and commit stats (mutation count). Deadlock aborts exactly one transaction. Unique indexes are re-checked at commit. |
| Partition query/read and batch write | Supported | PartitionRead, PartitionQuery, partitioned DML (including parameterized PostgreSQL statements), and BatchWrite are supported. |
| Instance, configuration, and instance-partition administration | Supported | Instance and instance-partition administration, custom instance configurations, and MoveInstance (metadata). List operations and instances support AIP-160 filter expressions. |
| Database administration and DDL | Supported | Database creation, DDL execution for both GoogleSQL and PostgreSQL, drop protection (UpdateDatabase), ListDatabaseOperations, split points (AddSplitPoints persisted to SPANNER\_SYS.USER\_SPLIT\_POINTS), and fine-grained access control database roles (CREATE/DROP ROLE, GRANT/REVOKE, ListDatabaseRoles). |
| Instance and database IAM policies | Supported | IAM policies are stored durably in LevelDB and returned through native endpoints with etags guarded. Fine-grained access control (FGAC) is enforced for sessions created with a creator\_role on queries, DML, reads, mutations, and change stream reads. Unauthenticated emulator connections bypass network IAM. |
| Backup, copy, restore, and backup schedules | Supported | With --data\_dir, CreateBackup, CopyBackup, GetBackup, ListBackups (with AIP-160 filter precedence), UpdateBackup, DeleteBackup, RestoreDatabase, and ListBackupOperations are supported. version\_time backups and full/incremental backup schedules persist cursors across restarts. |
| Long-running operation lifecycle | Supported | Native long-running operations lifecycle across instance, database, backup, copy, and restore calls, with AIP-160 filter support. |

### Features that need scoped checks

- GoogleSQL and PostgreSQL dialect types, DDL, query syntax, and metadata.
- Transaction isolation, wound-wait conflict handling, retries, locking, and commit metadata.
- Graph, vector, and full-text query behavior beyond parser or catalog acceptance.
- Fine-grained database roles, caller identity, and enforcement through every required API path.
- Backup, restore, point-in-time reads, schedules, change streams, and resume behavior.

A declaration or registered method alone does not establish these semantics. Keep any broader standalone dependency evidence separate from the current LocalCloud operation contract.

### Runtime and recovery limits

- Extended Spanner emulator image supports 140 features. Public-endpoint client matrix is 100% verified against native builds and packaged Docker image with Python (3.71.0), Go (1.95.1), Node.js (9.0.0), Java (6.123.0), JDBC (2.45.0), and PGAdapter (0.55.3 with pgJDBC and psql).
- Database roles and fine-grained access control (FGAC) are enforced for sessions created with a creator\_role. Unauthenticated emulator connections bypass IAM principal identity checks; stored IAM policies do not enforce network identity.
- Change streams require ExecuteStreamingSql; unary ExecuteSql rejects change-stream queries. With --data\_dir, stream definitions, records, partition history, and resume tokens survive restarts.
- Backups require --data\_dir; each backup is a full database copy. Customer-managed encryption keys (CMEK) are not implemented (data is plaintext).
- Cloud-only infrastructure (Google TrueTime hardware clock, multi-region Paxos quorum switching, physical split points and tablet distribution, physical cross-region migration, multi-tenant compute slicing) does not apply to local development.
- Ordinary container stop/start retains state; a mounted /var/lib/localcloud volume is required to retain state across container removal or replacement
- Rows use LevelDB and metadata uses JSON files.
- Known corruption/recovery risk; internal safety snapshots are not Cloud Spanner Backup API.

Verify production IAM, managed replication, regional availability, performance, and required functional behavior in Google Cloud before release.

---

## What is a GCP emulator?

> Understand local Google Cloud emulation, endpoint routing, support levels, and production limits.
>
> Source: https://local.cloud/docs/what-is-gcp-emulator/

A GCP emulator is a local implementation of selected Google Cloud API behavior. Applications reach it through a local REST, gRPC, or service-specific endpoint rather than a production `googleapis.com` endpoint.

“Emulator” does not imply full API, semantic, security, performance, or operational parity. Compatibility must be stated per operation and tested with the exact client and emulator release.

### Why use one?

A local emulator can help with:

- SDK endpoint wiring and serialization;
- deterministic local fixtures and setup/teardown logic;
- query and resource-definition feedback for documented operations;
- destructive tests against synthetic local data; and
- development without giving the local process real Google Cloud credentials.

It does not automatically provide zero cost, complete offline operation, identical CI results, or a safe production security boundary. LocalCloud can make outbound requests for configured telemetry, licensing, updates, live IAM, certificate probing, or scheduled HTTP work. The governing proprietary license also limits allowed personal, organization, commercial, and CI use.

### How routing works

Some Google clients honor emulator variables such as `PUBSUB_EMULATOR_HOST`; some accept explicit client endpoints; Terraform exposes provider-specific custom-endpoint variables; and some clients require transparent DNS/HTTPS routing. The recommended LocalCloud flow generates values for the running runtime:

```bash
localcloud start --local-only
eval "$(localcloud env)"
```

If a default port is already in use, the CLI picks another one. Use the endpoint values it returns instead of the default ports. If a client tries to contact real Google Cloud, stop rather than adding real credentials.

### LocalCloud implementation types

| Type | Meaning in LocalCloud |
| --- | --- |
| External emulator | A separate process supervised inside the container, such as BigQuery, Bigtable, Spanner, Cloud Storage, or Valkey. |
| Extended emulator | An upstream-derived emulator with local additions, such as Spanner. |
| Local facade | Gateway implementation of documented REST/gRPC workflows backed by local stores or processes. |
| Operator surface | Root routes such as `/health`, `/services`, `/env`, `/seed`, and `/terraform/readiness`; these are not Google Cloud APIs. |

Spanner REST port `5387` is not PostgreSQL wire and LocalCloud does not package PGAdapter. BigQuery is DuckDB-backed, with coverage documented per feature.

### What to validate in production

Before release, use a clean process without emulator/custom-endpoint variables and intentionally target an isolated real Google Cloud project. Validate IAM, quotas, networking, regions, concurrency, retries, ordering, durability, backups, performance, and every operation that is unsupported locally.

### Related pages

- [GCP emulator overview](https://local.cloud/gcp-emulator/): Every local service in one Docker container.
- [GCP emulator definition](https://local.cloud/glossary/gcp-emulator/): The term in one sentence.

---

## LocalCloud service catalog

> Browse guides for 27 Google Cloud services in LocalCloud: 25 run locally with setup steps, workflows, and code examples; 2 are unsupported.
>
> Source: https://local.cloud/services/

25 local services

Find connection details, workflows, and limits for every local service. Services that don't run locally are marked Unsupported.

Search services

[Compatibility](https://local.cloud/compatibility/)

Databases

### Databases services

Transactional, document, wide-column, relational, and cache workflows.

- [Firestore](https://local.cloud/services/firestore/): Document CRUD, query, and collection workflows; opt-in to save memory.
- [Bigtable](https://local.cloud/services/bigtable/): Row mutation, read, table administration, and PostgreSQL-backed data workflows. Pro tier, free during preview.
- [Spanner](https://local.cloud/services/spanner/): Spanner data and administration workflows over gRPC and REST. Pro tier, free during preview.
- [AlloyDB](https://local.cloud/services/alloydb/): AlloyDB cluster and instance control-plane workflows.
- [Memorystore (Redis/Valkey)](https://local.cloud/services/memorystore/): Valkey-backed RESP data workflows.
- [Cloud SQL](https://local.cloud/services/cloud-sql/): Local control-plane and MySQL data-plane workflows.

Messaging & Workflow

### Messaging & Workflow services

Events, jobs, scheduling, and orchestration.

- [Pub/Sub](https://local.cloud/services/pubsub/): Topic, subscription, publish, pull, and acknowledgement workflows.
- [Cloud Tasks](https://local.cloud/services/cloud-tasks/): Queue and task lifecycle workflows.
- [Cloud Scheduler](https://local.cloud/services/cloud-scheduler/): Schedule and job lifecycle workflows.
- [Cloud Workflows](https://local.cloud/services/cloud-workflows/): Workflow deployment and execution workflows.

Compute & Runtime

### Compute & Runtime services

Function, container, cluster, VM, and AI control-plane workflows.

- [Cloud Functions (2nd Gen)](https://local.cloud/services/cloud-functions/): Second-generation function control-plane workflows.
- [GKE](https://local.cloud/services/gke/): Cluster workflows with opt-in k3d runtime integration. Pro tier, free during preview.
- [Compute Engine](https://local.cloud/services/compute-engine/): Compute Engine doesn't run in LocalCloud; use Google Cloud for VM workloads.
- [Cloud Run](https://local.cloud/services/cloud-run/): Service and revision workflows with host-runtime integration. Pro tier, free during preview.
- [Vertex AI](https://local.cloud/services/vertex-ai/): Vertex AI doesn't run in LocalCloud; use Google Cloud for inference and training.

Security

### Security services

Secret, identity, and cryptographic API workflows.

- [Secret Manager](https://local.cloud/services/secret-manager/): Secret and version lifecycle workflows for local development.
- [Cloud IAM](https://local.cloud/services/cloud-iam/): IAM policy API workflows for local development.
- [Cloud KMS](https://local.cloud/services/cloud-kms/): Key-management and cryptographic workflows. Pro tier, free during preview.

Operations

### Operations services

Projects, service usage, billing metadata, logs, and metrics.

- [Cloud Resource Manager](https://local.cloud/services/cloud-resource-manager/): Project lifecycle workflows for local development.
- [Service Usage](https://local.cloud/services/service-usage/): Service enablement and metadata workflows.
- [Cloud Billing](https://local.cloud/services/cloud-billing/): Billing-account, budget, and cost metadata workflows.
- [Cloud Logging](https://local.cloud/services/cloud-logging/): Log ingestion, listing, metrics, and sink workflows.
- [Cloud Monitoring](https://local.cloud/services/cloud-monitoring/): Time-series, metric-descriptor, alerting, and dashboard workflows.

Storage

### Storage services

Buckets, objects, and local file workflows.

- [Cloud Storage](https://local.cloud/services/cloud-storage/): Bucket and object lifecycle workflows for local SDK and API development.

Analytics

### Analytics services

Local data processing, warehouse, and query workflows.

- [BigQuery](https://local.cloud/services/bigquery/): Dataset, table, query, scripting, and API workflows.
- [Dataproc](https://local.cloud/services/dataproc/): Dataproc cluster and job workflows in serverless and cluster modes with Docker execution.

Auxiliary Integration APIs

### Auxiliary integration APIs

Data lookup and fixture seeding APIs for other cloud services (e.g. BigQuery external tables); not offered as an individual Google Cloud service.

- [Google Sheets](https://local.cloud/services/google-sheets/): Auxiliary read-only values lookup API for BigQuery external tables and fixture seeding, selected by exact A1 range.

> **Technical availability is not a license grant**
>
> The governing proprietary license controls permitted use. Review it before personal, employer, organization, commercial, internal-tool, or CI use. Validate production behavior separately against real Google Cloud.

---

## AlloyDB

> Run AlloyDB locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/alloydb/

AlloyDB is Google Cloud’s PostgreSQL-compatible database service. LocalCloud combines AlloyDB resource metadata with a local PostgreSQL connection for application tests.

### Typical uses

Use when an application depends on PostgreSQL SQL, drivers, and transactions, and its production deployment targets AlloyDB. Exercise resource provisioning alongside SQL application tests locally.

Examples

- PostgreSQL application backends
- Database provisioning and connection tests

Databases

Connection

Environment variable

`ALLOYDB_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** Community
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and ALLOYDB_EMULATOR_HOST
eval "$(localcloud env)"
```

Provision metadata and query PostgreSQL

1. Create local cluster and instance metadata.
2. Connect the application to the documented PostgreSQL endpoint.
3. Create a table, insert a fixture, and query it back.

### Documented workflows

- Cluster/instance CRUD and local PostgreSQL access
- Configuration patching, flag discovery, and backup metadata restore

### Service boundaries

- Backup restore covers metadata
- No advanced AlloyDB engine behavior or replicas
- Managed regional failover is cloud-only

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use AlloyDB with an AI agent

Before the agent changes application logic, have it create local AlloyDB state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official AlloyDB documentation](https://docs.cloud.google.com/alloydb/docs/overview): service concepts and cloud usage.

---

## BigQuery emulator

> Run BigQuery locally: GoogleSQL datasets, tables, queries, scripting, external tables, and the Storage API on ports 5388 and 5389.
>
> Source: https://local.cloud/services/bigquery/

BigQuery is a SQL analytics warehouse for exploring and transforming datasets. It is designed for reporting, aggregations, and analytical pipelines rather than individual application record updates.

### Typical uses

Use when you need to scan datasets, join analytical tables, and calculate aggregates with SQL. Validate reporting queries and transformation outputs against small local fixtures.

Examples

- Analytics and business reporting
- SQL transformations and model experiments

Analytics

Connection

Environment variable

`BIGQUERY_EMULATOR_HOST=http://localhost:5388`

Runtime details

- **Endpoints:** HTTP/REST :5388 · gRPC :5389
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Custom Emulator

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Hello world

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and BIGQUERY_EMULATOR_HOST
eval "$(localcloud env)"
```

Python

#### Run a deterministic GoogleSQL query

2\. Install SDK · shell

```
python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-bigquery
```

3\. Save as hello.py

```
import os
from google.auth.credentials import AnonymousCredentials
from google.cloud import bigquery

client = bigquery.Client(
    project=os.environ['GOOGLE_CLOUD_PROJECT'],
    credentials=AnonymousCredentials(),
    client_options={"api_endpoint": os.environ["BIGQUERY_EMULATOR_HOST"]},
)
rows = list(client.query("SELECT 'Hello from LocalCloud!' AS message").result(timeout=30))
assert rows[0].message == 'Hello from LocalCloud!'
print(rows[0].message)
client.close()
```

4\. Run`python hello.py`

[Full example guide](https://local.cloud/docs/sdk-examples/#bigquery-deterministic-query)

### Documented workflows

- Datasets, tables, clones, and time travel
- Row access policies, top-level policy tags, and masking
- Joins, window functions, CTEs, PIVOT/UNPIVOT, and MERGE
- Procedural scripts, stored procedures, and dynamic SQL
- Jobs, dry runs, scheduled queries, and selected ML models
- Materialized views and INFORMATION\_SCHEMA
- Emulated GCS: CSV, JSONL, Parquet, Avro, ORC; EXTERNAL\_QUERY
- gRPC Storage Read/Write with Avro and Arrow

### Service boundaries

- Function/input-specific SQL limits; check the feature matrix
- No ingestion-time partitioning or nested policy tags
- No native Bigtable, Sheets, HTTP, or local-file external sources
- Model, ML transform, and geography input limits
- Managed reservations, production IAM, and fleet scale are cloud-only

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.
- [Official SDK code samples](https://docs.cloud.google.com/bigquery/docs/samples): Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Agent testing

### Use BigQuery with an AI agent

Before the agent changes application logic, have it create local BigQuery state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### BigQuery local test

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### BigQuery emulator FAQ

#### How do I run BigQuery locally?

Install the LocalCloud CLI, start the runtime, and export its environment, as in the example above.

#### Which environment variable points the SDK at the local BigQuery?

LocalCloud exports BIGQUERY\_EMULATOR\_HOST=http://localhost:5388. Use the generated value, because the CLI picks another port when the default is in use. Some SDKs also need explicit client endpoint options; the variable alone does not route them locally.

#### Does the local BigQuery behave exactly like Google Cloud?

No. LocalCloud runs the documented workflows on this page within the service boundaries listed here. Validate behavior against real BigQuery before production deployment.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [BigQuery feature reference](https://local.cloud/docs/bigquery-emulator-features/): detailed operation and recovery notes.
- [Official BigQuery documentation](https://docs.cloud.google.com/bigquery/docs/introduction): service concepts and cloud usage.

---

## Bigtable emulator

> Run Bigtable locally: data, administration, GoogleSQL, change streams, materialized views, backups, and IAM workflows in one Docker container.
>
> Source: https://local.cloud/services/bigtable/

Bigtable is a wide-column database for large key-based datasets. Rows are sorted by key, making it useful for time-series data, event histories, and fast range reads.

### Typical uses

Use when high-volume records can be organized by a row key and retrieved through point lookups or bounded key-range scans. Design the row key around your most frequent reads.

Examples

- Sensor readings and time-series events
- Per-user activity and transaction histories

Databases

Connection

Environment variable

`BIGTABLE_EMULATOR_HOST=localhost:5385`

Runtime details

- **Endpoints:** gRPC :5385
- **Minimum tier:** [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier)
- **Persistence:** service-data
- **Implementation:** Custom Emulator

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Hello world

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and BIGTABLE_EMULATOR_HOST
eval "$(localcloud env)"
```

Python

#### Write and read a Bigtable cell

2\. Install SDK · shell

```
python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-bigtable
```

3\. Save as hello.py

```
import os
from uuid import uuid4
from google.cloud import bigtable

assert os.environ['BIGTABLE_EMULATOR_HOST']
client = bigtable.Client(project=os.environ['GOOGLE_CLOUD_PROJECT'], admin=True)
instance = client.instance('guide-' + uuid4().hex[:12])
instance.create(clusters=[instance.cluster('local', location_id='us-central1-a', serve_nodes=1)]).result(timeout=60)
try:
    table = instance.table('messages')
    table.create(column_families={'cf': None})
    row = table.direct_row(b'row-1')
    row.set_cell('cf', b'message', b'hello')
    row.commit()
    message = table.read_row(b'row-1').cells['cf'][b'message'][0].value
    assert message == b'hello'
    print(message.decode())
    table.delete()
finally:
    instance.delete()
    client.close()
```

4\. Run`python hello.py`

[Full example guide](https://local.cloud/docs/sdk-examples/#bigtable-python)

### Documented workflows

- Instances, clusters, tables, families, app profiles, and schema bundles
- Atomic mutations, row filters including Sink, aggregates, and read sessions
- Prepared GoogleSQL, logical views, and continuous materialized views
- Change streams
- Data-bearing backups, copy/restore, and seven-day table undelete
- IAM policy storage, cbt, and Console browsing

### Service boundaries

- Sink preserves cells past later filters; invalid inside a Condition
- Verify backup listing and project deletion through the native admin API
- Validate Sink filters, PostgreSQL-backed durability, and cbt scripts in your own test suite
- Delete owned backups and clear resource deletion protection before instance or project deletion
- Failed project cleanup keeps the project record; confirm deletion through the native admin API
- Native backup listing supports filter/order/pagination; REST ignores those options
- Confirm writes through the native API; the Console view may not surface rejected writes
- Permissive IAM; one change-stream partition
- No query statistics, view parameters, or legacy snapshot RPCs
- Local encodings for HLL++ bytes and multi-column view keys

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.
- [Official SDK code samples](https://docs.cloud.google.com/bigtable/docs/samples): Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Agent testing

### Use Bigtable with an AI agent

Before the agent changes application logic, have it create local Bigtable state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Bigtable emulator FAQ

#### How do I run Bigtable locally?

Install the LocalCloud CLI, start the runtime, and export its environment, as in the example above.

#### Which environment variable points the SDK at the local Bigtable?

LocalCloud exports BIGTABLE\_EMULATOR\_HOST=localhost:5385. Use the generated value, because the CLI picks another port when the default is in use. Some SDKs also need explicit client endpoint options; the variable alone does not route them locally.

#### Does the local Bigtable behave exactly like Google Cloud?

No. LocalCloud runs the documented workflows on this page within the service boundaries listed here. Validate behavior against real Bigtable before production deployment.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Bigtable feature reference](https://local.cloud/docs/bigtable-emulator-features/): detailed operation and recovery notes.
- [Official Bigtable documentation](https://docs.cloud.google.com/bigtable/docs/overview): service concepts and cloud usage.

---

## Cloud Billing

> Run Cloud Billing locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-billing/

Cloud Billing connects projects to billing accounts on Google Cloud. LocalCloud exposes selected account and project billing metadata for provisioning tests.

### Typical uses

Use when provisioning automation needs to discover a billing account or verify a project's billing association. Local tests exercise the metadata flow with test-owned resources.

Examples

- Billing-account lookup flows
- Project billing-link metadata tests

Operations

Connection

Environment variable

`CLOUD_BILLING_EMULATOR_HOST=http://localhost:5380`

Runtime details

- **Endpoints:** HTTP/REST :5380
- **Minimum tier:** Community
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and CLOUD_BILLING_EMULATOR_HOST
eval "$(localcloud env)"
```

Check a project’s billing metadata

1. Create the documented local billing metadata.
2. Read or update the project billing association.
3. Verify the returned account and billing-enabled fields.

### Documented workflows

- Billing-account and budget metadata CRUD; selected Terraform paths

### Service boundaries

- No cost accumulation or threshold notifications
- No billing exports or budget-triggered automation

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Cloud Billing with an AI agent

Before the agent changes application logic, have it create local Cloud Billing state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Billing documentation](https://docs.cloud.google.com/billing/docs/how-to/manage-billing-account): service concepts and cloud usage.

---

## Cloud Functions (2nd Gen)

> Run Cloud Functions (2nd Gen) locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-functions/

Cloud Functions runs functions in response to HTTP requests or events. LocalCloud stores function metadata and routes supported invocations to a handler you run locally.

### Typical uses

Use when a small handler processes an HTTP request or event and can run as an independently invoked function. Locally, test routing to your own running handler.

Examples

- HTTP function handlers
- Pub/Sub-triggered application logic

Compute & Runtime

Connection

Environment variable

`CLOUD_FUNCTIONS_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** Community
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and CLOUD_FUNCTIONS_EMULATOR_HOST
eval "$(localcloud env)"
```

Exercise an HTTP function handler

1. Run the handler in your own local process.
2. Register function metadata with its execution target.
3. Invoke through LocalCloud and assert the handler response.

### Documented workflows

- Second-generation function metadata CRUD
- HTTP forwarding and Pub/Sub trigger routing

### Service boundaries

- Requires your own execution target
- No source builds or managed function containers
- No Firestore/Storage/Audit Log Eventarc triggers or Google identity tokens

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Cloud Functions (2nd Gen) with an AI agent

Before the agent changes application logic, have it create local Cloud Functions (2nd Gen) state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Functions (2nd Gen) documentation](https://docs.cloud.google.com/functions/docs/concepts/overview): service concepts and cloud usage.

---

## Cloud IAM

> Run Cloud IAM locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-iam/

Identity and Access Management connects principals, roles, and permissions to resources. It defines who can perform which actions in a Google Cloud project.

### Typical uses

Use when resource access depends on which user or service account is making a request, and policies must be managed and tested as part of provisioning.

Examples

- Role and service-account provisioning
- Policy-aware application tests

Security

Connection

Environment variable

`IAM_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** Community
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and IAM_EMULATOR_HOST
eval "$(localcloud env)"
```

Check a local allow policy

1. Create a test service account and custom role.
2. Store an allow policy on a supported resource.
3. Exercise a documented permission check in the selected IAM mode.

### Documented workflows

- Allow policies, permission checks, supported conditions, and project inheritance
- Custom roles and grantable-role queries
- Service-account metadata, key enable/disable, and testable-permission queries
- Local access/ID tokens, impersonation, and blob/JWT signing
- OIDC workload identity pools, providers, and token exchange

### Service boundaries

- Enforcement varies by service, transport, and IAM mode
- Open/permissive probes do not establish enforced access
- No full CEL, organization/folder ancestry, or deny policies
- Tokens use LocalCloud's issuer; configure receivers to trust its local JWKS
- Federation uses durable OIDC providers; other enterprise identity integrations require validation

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Cloud IAM with an AI agent

Before the agent changes application logic, have it create local Cloud IAM state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud IAM documentation](https://docs.cloud.google.com/iam/docs/overview): service concepts and cloud usage.

---

## Cloud KMS

> Run Cloud KMS locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-kms/

Cloud KMS manages cryptographic keys and their versions. Applications use keys to encrypt data, sign messages, or verify authenticity without storing key material in application code.

### Typical uses

Use when applications encrypt, decrypt, sign, or verify data using managed keys and explicit key versions. Keep cryptographic key lifecycle separate from application payloads.

Examples

- Encryption and decryption
- Signing, MACs, and key lifecycle tests

Security

Connection

Environment variable

`CLOUD_KMS_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC + HTTP/REST :5380
- **Minimum tier:** [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier)
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and CLOUD_KMS_EMULATOR_HOST
eval "$(localcloud env)"
```

Encrypt and decrypt with a software key

1. Create a key ring and an eligible software crypto key.
2. Encrypt a small payload through the KMS API.
3. Decrypt it and assert the original bytes are restored.

### Documented workflows

- Locations, random bytes, keys/versions, rotation, destruction/restoration, and eligible deletion
- SOFTWARE symmetric/asymmetric cryptography, public keys, and MACs
- Supported post-quantum signing/decapsulation and wrapped key imports
- Strict IAM, conditions, audits, metrics, and authenticated Workflows connectors
- Secret Manager CMEK, project Inventory, and Autokey/KeyHandles

### Service boundaries

- SOFTWARE keys; hardware custody and Google authority are cloud-only
- Inventory/Autokey: project-owned global Secret Manager resources only
- No folder ancestry or other protected-resource types
- KeyRing deletion isn't guaranteed to match Google Cloud

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.
- [Official SDK code samples](https://docs.cloud.google.com/kms/docs/samples): Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Agent testing

### Use Cloud KMS with an AI agent

Before the agent changes application logic, have it create local Cloud KMS state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud KMS documentation](https://docs.cloud.google.com/kms/docs/key-management-service): service concepts and cloud usage.

---

## Cloud Logging

> Run Cloud Logging locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-logging/

Cloud Logging collects and queries structured application logs. It helps developers investigate requests, errors, and resource activity.

### Typical uses

Use when you need searchable records of individual application events, including severity, structured fields, and request IDs for investigating failures.

Examples

- Application log ingestion
- Request tracing and audit inspection

Operations

Connection

Environment variable

`CLOUD_LOGGING_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** Community
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and CLOUD_LOGGING_EMULATOR_HOST
eval "$(localcloud env)"
```

Find a failed request in structured logs

1. Write log entries containing severity and a request ID.
2. Query with a supported filter.
3. Check that the expected entry and fields are returned.

### Documented workflows

- Log ingestion, listing, and local filtering
- Sink configuration and runtime/KMS audit events
- Logs-based metric definition create/get/list/update/delete APIs

### Service boundaries

- Limited Google filter semantics
- Metric definitions do not derive values from log entries
- Validate log-based metrics, exclusions, and sink delivery in Google Cloud

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Cloud Logging with an AI agent

Before the agent changes application logic, have it create local Cloud Logging state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Logging documentation](https://docs.cloud.google.com/logging/docs/overview): service concepts and cloud usage.

---

## Cloud Monitoring

> Run Cloud Monitoring locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-monitoring/

Cloud Monitoring stores time-series metrics and supports observability for applications and infrastructure. LocalCloud provides documented metric writes, queries, and configuration metadata.

### Typical uses

Use when application health is expressed as numeric measurements over time, with labels identifying resources or components. Test metric ingestion and time-window queries with deterministic points.

Examples

- Custom application metrics
- Metric and alert-configuration tests

Operations

Connection

Environment variable

`CLOUD_MONITORING_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** Community
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and CLOUD_MONITORING_EMULATOR_HOST
eval "$(localcloud env)"
```

Write and query a custom metric

1. Create a metric descriptor for completed requests.
2. Write timestamped points with consistent labels.
3. Query the time interval and verify the returned values.

### Documented workflows

- Time-series and metric-descriptor create/list APIs
- Notification-channel metadata
- Alert-policy create/get/list/update/delete APIs

### Service boundaries

- Limited query alignment/aggregation
- Validate alert evaluation, notifications, uptime execution, and dashboards in Google Cloud

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Cloud Monitoring with an AI agent

Before the agent changes application logic, have it create local Cloud Monitoring state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Monitoring documentation](https://docs.cloud.google.com/monitoring/docs/monitoring-overview): service concepts and cloud usage.

---

## Cloud Resource Manager

> Run Cloud Resource Manager locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-resource-manager/

Resource Manager organizes Google Cloud resources into projects, folders, and organizations. LocalCloud implements documented project lifecycle operations for local provisioning flows.

### Typical uses

Use when automation needs to create, look up, or delete projects and carry their IDs through resource provisioning. Projects provide the scope for the rest of your setup.

Examples

- Project provisioning
- Project-scoped test environments

Operations

Connection

Environment variable

`CLOUD_RESOURCE_MANAGER_EMULATOR_HOST=http://localhost:5380`

Runtime details

- **Endpoints:** HTTP/REST :5380
- **Minimum tier:** Community
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and CLOUD_RESOURCE_MANAGER_EMULATOR_HOST
eval "$(localcloud env)"
```

Create a disposable project

1. Create a project through the supported API.
2. Poll its long-running operation until completion.
3. Read its metadata and remove it after the test.

### Documented workflows

- Project CRUD through v1/v3 APIs; completed operation polling
- Project auto-registration on supported entry points outside strict mode

### Service boundaries

- No organization/folder lifecycle, moves, search, or full ancestry
- No project auto-registration on direct emulator listeners

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Provision resources with Terraform](https://local.cloud/docs/terraform/#supported-terraform-resources): Documented resources, provider configuration, and local routing setup.
- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Cloud Resource Manager with an AI agent

Before the agent changes application logic, have it create local Cloud Resource Manager state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Resource Manager documentation](https://docs.cloud.google.com/resource-manager/docs/cloud-platform-resource-hierarchy): service concepts and cloud usage.

---

## Cloud Run

> Run Cloud Run locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-run/

Cloud Run runs containerized applications behind HTTP endpoints on Google Cloud. LocalCloud runs supported service containers through Docker for local request tests.

### Typical uses

Use when you can package an HTTP application in a container image and test it through a service URL. LocalCloud runs supported service containers with Docker.

Examples

- Containerized HTTP APIs
- Service deployment and update tests

Compute & Runtime

Cloud Run is opt-in to save memory. Add `cloudrun` to the services you start, for example `localcloud start --local-only --services cloudrun,gcs,pubsub`; `--services` sets the exact list.

Connection

Environment variable

`CLOUD_RUN_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier)
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only --services cloudrun
# Export GOOGLE_CLOUD_PROJECT and CLOUD_RUN_EMULATOR_HOST
eval "$(localcloud env)"
```

Deploy and call a containerized API

1. Build a test HTTP application into a container image.
2. Create a local Cloud Run service using that image.
3. Call its endpoint and verify the response after an update.

### Documented workflows

- Service/revision metadata
- Docker container execution on service create/update

### Service boundaries

- Requires Docker runtime access
- No jobs, domain mappings, or full revision traffic splitting

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Cloud Run with an AI agent

Before the agent changes application logic, have it create local Cloud Run state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Run documentation](https://docs.cloud.google.com/run/docs/overview/what-is-cloud-run): service concepts and cloud usage.

---

## Cloud Scheduler

> Run Cloud Scheduler locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-scheduler/

Cloud Scheduler runs jobs on a cron schedule. It triggers HTTP endpoints or messaging targets for recurring application work.

### Typical uses

Use when work must recur on a cron schedule in a chosen time zone, with an HTTP endpoint or messaging target receiving each scheduled trigger.

Examples

- Scheduled reports and maintenance
- Recurring HTTP or Pub/Sub triggers

Messaging & Workflow

Connection

Environment variable

`CLOUD_SCHEDULER_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC + HTTP/REST :5380
- **Minimum tier:** Community
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and CLOUD_SCHEDULER_EMULATOR_HOST
eval "$(localcloud env)"
```

Trigger a recurring maintenance handler

1. Create an HTTP job with a cron schedule and time zone.
2. Run it manually against a local handler.
3. Inspect the execution history and retry behavior.

### Documented workflows

- Job CRUD, pause/resume, and manual runs
- Timezone-aware cron and schedule previews
- HTTP/Pub/Sub delivery, retries, deadlines, and attempt history
- HTTP delivery with locally issued OAuth/OIDC credentials

### Service boundaries

- No App Engine targets; authenticated receivers must trust the local issuer and JWKS
- No interrupted-attempt replay or downtime backfill
- Stored policies do not enforce per-job authorization

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Cloud Scheduler with an AI agent

Before the agent changes application logic, have it create local Cloud Scheduler state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Scheduler documentation](https://docs.cloud.google.com/scheduler/docs/overview): service concepts and cloud usage.

---

## Cloud SQL

> Run Cloud SQL locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-sql/

Cloud SQL is a managed relational database service. LocalCloud exposes supported instance, database, and user APIs with local PostgreSQL and MySQL engines for application tests.

### Typical uses

Use when your application relies on a relational schema, SQL migrations, and transactions through PostgreSQL or MySQL drivers. Test database and user provisioning alongside application queries.

Examples

- Relational application backends
- Database provisioning and migration tests

Databases

Connection

Environment variable

`CLOUD_SQL_EMULATOR_HOST=http://localhost:5380`

Runtime details

- **Endpoints:** HTTP/REST :5380 · PostgreSQL :5391 · MySQL :5406
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and CLOUD_SQL_EMULATOR_HOST
eval "$(localcloud env)"
```

Provision a database for application tests

1. Create supported instance metadata, a database, and a user.
2. Connect the application to the selected local SQL engine.
3. Apply a migration and verify a fixture query.

### Documented workflows

- Instance/database/user lifecycle; PostgreSQL and on-demand MySQL 8.4
- Backup/replica administration, restore/import/export management, and upgrade prechecks
- Development certificate maintenance APIs

### Service boundaries

- Shared installed engines; version labels do not provision separate versions
- No per-instance database flags; infrastructure settings are metadata
- No managed backup recovery or replication guarantees
- Development certificates for local connections; validate production TLS settings in Google Cloud

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Provision resources with Terraform](https://local.cloud/docs/terraform/#supported-terraform-resources): Documented resources, provider configuration, and local routing setup.
- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Cloud SQL with an AI agent

Before the agent changes application logic, have it create local Cloud SQL state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud SQL documentation](https://docs.cloud.google.com/sql/docs/introduction): service concepts and cloud usage.

---

## Cloud Storage emulator

> Run Cloud Storage locally: buckets, object upload and download, IAM, Pub/Sub notifications, and HMAC-signed requests on port 5382.
>
> Source: https://local.cloud/services/cloud-storage/

Cloud Storage stores files as objects inside buckets. Use it for application uploads, datasets, and artifacts that need an object-storage API.

### Typical uses

Use when your application stores unstructured files and addresses each object by bucket and name, with uploads, downloads, and object metadata handled through an API.

Examples

- User uploads and downloads
- Data pipeline inputs and outputs

Storage

Connection

Environment variable

`STORAGE_EMULATOR_HOST=http://localhost:5382`

Runtime details

- **Endpoints:** HTTP/REST :5382
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Third-Party Emulator

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Hello world

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and STORAGE_EMULATOR_HOST
eval "$(localcloud env)"
```

Python

#### Upload and download an object

2\. Install SDK · shell

```
python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-storage
```

3\. Save as hello.py

```
import os
from google.api_core.exceptions import NotFound
from google.auth.credentials import AnonymousCredentials
from google.cloud import storage

assert os.environ['STORAGE_EMULATOR_HOST']
client = storage.Client(
    project=os.environ['GOOGLE_CLOUD_PROJECT'],
    credentials=AnonymousCredentials(),
)
bucket = client.bucket("localcloud-sdk-example")

try:
    bucket.reload()
except NotFound:
    bucket.create()

blob = bucket.blob("data.txt")
blob.upload_from_string("Hello from LocalCloud!")
print(blob.download_as_text())
```

4\. Run`python hello.py`

[Full example guide](https://local.cloud/docs/sdk-examples/#cloud-storage-python)

Node.js

#### Upload and download an object

2\. Install SDK · shell

```
npm install @google-cloud/storage
```

3\. Save as hello.cjs

```
const { Storage } = require('@google-cloud/storage');

if (!process.env.STORAGE_EMULATOR_HOST || !process.env.GOOGLE_CLOUD_PROJECT) {
  throw new Error('Export the LocalCloud environment before running this example.');
}
const storage = new Storage({ projectId: process.env.GOOGLE_CLOUD_PROJECT });
const bucket = storage.bucket('localcloud-sdk-example');

async function main() {
  const [exists] = await bucket.exists();
  if (!exists) await storage.createBucket(bucket.name);
  await bucket.file('data.txt').save('Hello from LocalCloud!');
  const [content] = await bucket.file('data.txt').download();
  console.log(content.toString());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

4\. Run`node hello.cjs`

[Full example guide](https://local.cloud/docs/sdk-examples/#cloud-storage-nodejs)

### Documented workflows

- Bucket CRUD; object upload, download, listing, and deletion
- Bucket IAM and mode-aware object authorization
- Object event delivery to local Pub/Sub topics
- HMAC keys and signed XML requests

### Service boundaries

- No bucket versioning, archive events, or managed folders
- No lifecycle scheduling or retention enforcement
- Notifications need precreated Pub/Sub topics
- No event ordering or atomic object/event delivery guarantees

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.
- [Official SDK code samples](https://docs.cloud.google.com/storage/docs/samples): Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Agent testing

### Use Cloud Storage with an AI agent

Before the agent changes application logic, have it create local Cloud Storage state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Cloud Storage local test

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Cloud Storage emulator FAQ

#### How do I run Cloud Storage locally?

Install the LocalCloud CLI, start the runtime, and export its environment, as in the example above.

#### Which environment variable points the SDK at the local Cloud Storage?

LocalCloud exports STORAGE\_EMULATOR\_HOST=http://localhost:5382. Use the generated value, because the CLI picks another port when the default is in use. Some SDKs also need explicit client endpoint options; the variable alone does not route them locally.

#### Does the local Cloud Storage behave exactly like Google Cloud?

No. LocalCloud runs the documented workflows on this page within the service boundaries listed here. Validate behavior against real Cloud Storage before production deployment.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Storage documentation](https://docs.cloud.google.com/storage/docs/introduction): service concepts and cloud usage.

---

## Cloud Tasks

> Run Cloud Tasks locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-tasks/

Cloud Tasks queues work for later delivery to a handler. Rate limits, retries, and scheduling help control how background requests reach application workers.

### Typical uses

Use when a known handler should process queued work with controlled dispatch rates, scheduled delivery, and per-task retry behavior.

Examples

- Deferred HTTP work
- Rate-limited background processing

Messaging & Workflow

Connection

Environment variable

`CLOUD_TASKS_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and CLOUD_TASKS_EMULATOR_HOST
eval "$(localcloud env)"
```

Dispatch a background HTTP task

1. Create a queue with a dispatch rate and retry policy.
2. Enqueue a request for a local HTTP handler.
3. Inspect attempts and verify the handler completes the work.

### Documented workflows

- Queue lifecycle, pause/resume, and purge
- Task CRUD and manual/automatic HTTP dispatch
- Rate/concurrency limits, deadlines, retries, and attempt history
- HTTP delivery with locally issued OAuth/OIDC credentials

### Service boundaries

- No App Engine delivery or routing/header overrides
- Authenticated receivers must trust LocalCloud's issuer and JWKS
- No logging sampling
- Restart may redeliver; pause/purge/delete cannot cancel in-flight requests
- Check attempt history before replaying ambiguous requests

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Provision resources with Terraform](https://local.cloud/docs/terraform/#supported-terraform-resources): Documented resources, provider configuration, and local routing setup.
- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Cloud Tasks with an AI agent

Before the agent changes application logic, have it create local Cloud Tasks state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Tasks documentation](https://docs.cloud.google.com/tasks/docs/dual-overview): service concepts and cloud usage.

---

## Cloud Workflows

> Run Cloud Workflows locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-workflows/

Workflows orchestrates a sequence of API calls and application steps. It makes retries, branching, and execution state explicit in a workflow definition.

### Typical uses

Use when a process coordinates several API calls and needs explicit sequencing, branching, retries, and a queryable execution result.

Examples

- Multi-step service orchestration
- HTTP integrations with retry handling

Messaging & Workflow

Connection

Environment variable

`WORKFLOWS_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** Community
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and WORKFLOWS_EMULATOR_HOST
eval "$(localcloud env)"
```

Coordinate two local HTTP services

1. Deploy a definition using documented HTTP calls and expressions.
2. Start an execution with a small input payload.
3. Inspect step history and verify the returned result.

### Documented workflows

- Workflow deployment and lifecycle
- Local interpreter, standard library, and execution step history

### Service boundaries

- Limited connector and expression support
- Active executions fail on restart with InstanceRestart

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Cloud Workflows with an AI agent

Before the agent changes application logic, have it create local Cloud Workflows state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Workflows documentation](https://docs.cloud.google.com/workflows/docs/overview): service concepts and cloud usage.

---

## Compute Engine

> Compute Engine doesn't run in LocalCloud yet; local support is planned. Use Google Cloud for Compute Engine and read the official documentation.
>
> Source: https://local.cloud/services/compute-engine/

Unsupported

Compute Engine runs virtual machines with configurable CPU, memory, disks, and networking. Local VM execution is planned for LocalCloud and is not available yet.

Compute & Runtime

Local availability

### Not available locally

Compute Engine doesn't run in LocalCloud; use Google Cloud for VM workloads.

- Local VM execution: not available yet
- Disks, snapshots, templates, VPCs: use Google Cloud
- Local stub routes only

[Read the official Compute Engine documentation](https://docs.cloud.google.com/compute/docs/overview)

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Official Compute Engine documentation](https://docs.cloud.google.com/compute/docs/overview): service concepts and cloud usage.

---

## Dataproc

> Run Dataproc locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/dataproc/

Dataproc provides managed Spark and Hadoop execution on Google Cloud. LocalCloud runs supported cluster jobs and serverless batches through local Docker runtimes.

### Typical uses

Use when a pipeline uses Spark or Hadoop to transform partitioned datasets, and you need to submit jobs or serverless batches through the Dataproc API.

Examples

- Spark ETL and data transformations
- Hadoop and batch-processing tests

Analytics

Connection

Environment variable

`DATAPROC_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** Community
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and DATAPROC_EMULATOR_HOST
eval "$(localcloud env)"
```

Run a small Spark transformation

1. Prepare an input fixture and a Spark job.
2. Submit a supported cluster job or serverless batch locally.
3. Inspect job status and verify the transformed output.

### Documented workflows

- Local cluster lifecycle
- Spark/Hadoop execution in cluster and serverless modes

### Service boundaries

- Requires Docker daemon access
- Cloud scaling, automated node repair, and production SLAs are cloud-only

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Run Dataproc through local Docker](https://local.cloud/blog/run-dataproc-locally-docker/): Execution setup, job lifecycle, and Docker runtime boundaries.
- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Dataproc with an AI agent

Before the agent changes application logic, have it create local Dataproc state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Dataproc documentation](https://docs.cloud.google.com/managed-spark/docs/concepts/clusters-overview): service concepts and cloud usage.

---

## Firestore emulator

> Run Firestore document and query workflows locally. Firestore is opt-in: add firestore to the --services list when you start LocalCloud.
>
> Source: https://local.cloud/services/firestore/

Firestore is a document database that organizes application data into collections and documents. It suits flexible records such as profiles, catalogs, and application state.

### Typical uses

Use when records have evolving fields and fit a collection-and-document model, with reads driven by document IDs or indexed field queries.

Examples

- User profiles and product catalogs
- Document-based application backends

Databases

Firestore is opt-in to save memory. Add `firestore` to the services you start, for example `localcloud start --local-only --services firestore,gcs,pubsub`; `--services` sets the exact list.

Connection

Environment variable

`FIRESTORE_EMULATOR_HOST=localhost:5384`

Runtime details

- **Endpoints:** gRPC :5384
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Google Official

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Hello world

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only --services firestore
# Export GOOGLE_CLOUD_PROJECT and FIRESTORE_EMULATOR_HOST
eval "$(localcloud env)"
```

Python

#### Create, read, and update a document

2\. Install SDK · shell

```
python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-firestore
```

3\. Save as hello.py

```
import os
from uuid import uuid4
from google.cloud import firestore

assert os.environ['FIRESTORE_EMULATOR_HOST']
client = firestore.Client(project=os.environ['GOOGLE_CLOUD_PROJECT'])
document = client.collection('guide').document(uuid4().hex)
try:
    document.set({'message': 'hello'}, timeout=30)
    message = document.get(timeout=30).get('message')
    assert message == 'hello'
    print(message)
    document.update({'message': 'updated'}, timeout=30)
    assert document.get(timeout=30).get('message') == 'updated'
finally:
    document.delete(timeout=30)
    client.close()
```

4\. Run`python hello.py`

[Full example guide](https://local.cloud/docs/sdk-examples/#firestore-python)

### Documented workflows

- Document CRUD
- Queries and single-field indexes

### Service boundaries

- Opt-in: add firestore to localcloud start --services
- Validate composite indexes, concurrent transactions, listeners, and transforms
- Security Rules and Firestore triggers need runtime validation

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Firestore with an AI agent

Before the agent changes application logic, have it create local Firestore state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Firestore emulator FAQ

#### How do I run Firestore locally?

Install the LocalCloud CLI, start the runtime, and export its environment, as in the example above. Firestore is opt-in, so start it with localcloud start --local-only --services firestore,gcs,pubsub.

#### Which environment variable points the SDK at the local Firestore?

LocalCloud exports FIRESTORE\_EMULATOR\_HOST=localhost:5384. Use the generated value, because the CLI picks another port when the default is in use. Some SDKs also need explicit client endpoint options; the variable alone does not route them locally.

#### Does the local Firestore behave exactly like Google Cloud?

No. LocalCloud runs the documented workflows on this page within the service boundaries listed here. Validate behavior against real Firestore before production deployment.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Firestore documentation](https://docs.cloud.google.com/firestore/native/docs/overview): service concepts and cloud usage.

---

## GKE

> Run GKE locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/gke/

Google Kubernetes Engine manages Kubernetes clusters for container workloads. LocalCloud uses k3d to provide a local Kubernetes runtime alongside supported cluster metadata.

### Typical uses

Use when deployment depends on Kubernetes manifests and APIs, and you need cluster provisioning plus pod readiness checks. Local tests require Docker and k3d.

Examples

- Kubernetes deployment tests
- Cluster provisioning and readiness checks

Compute & Runtime

GKE is opt-in to save memory. Add `gke` to the services you start, for example `localcloud start --local-only --services gke,gcs,pubsub`; `--services` sets the exact list.

Connection

Environment variable

`GKE_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380 · k3d :5443
- **Minimum tier:** [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier)
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only --services gke
# Export GOOGLE_CLOUD_PROJECT and GKE_EMULATOR_HOST
eval "$(localcloud env)"
```

Deploy to a local Kubernetes cluster

1. Create a supported cluster with Docker and k3d available.
2. Connect kubectl using the local cluster configuration.
3. Deploy a test workload and check that its pods become ready.

### Documented workflows

- Cluster metadata lifecycle
- Real local Kubernetes clusters through k3d
- Pod ADC through annotated Kubernetes-to-Google service-account bindings

### Service boundaries

- Requires k3d and Docker
- No node-pool creation, autoscaling, resize, or upgrades
- GKE REST cluster calls require AlloyDB disabled; gRPC is separate
- Pod identity requires the service-account annotation and workloadIdentityUser grant; direct principal federation is unsupported

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use GKE with an AI agent

Before the agent changes application logic, have it create local GKE state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official GKE documentation](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/kubernetes-engine-overview): service concepts and cloud usage.

---

## Google Sheets

> Use the Google Sheets integration API locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/google-sheets/

Google Sheets exposes spreadsheet data through an API. LocalCloud provides a read-only values API for testing applications that consume tabular fixtures.

### Typical uses

Use when an application consumes small, human-maintained lookup tables through A1 ranges. Seed read-only spreadsheet fixtures locally to test how those rows are interpreted.

Examples

- Spreadsheet-backed lookup data
- Deterministic fixtures for data consumers

Auxiliary Integration APIs

Auxiliary API connection

Environment variable

`SHEETS_EMULATOR_HOST=http://localhost:5380`

Runtime details

- **Endpoints:** HTTP/REST :5380
- **Minimum tier:** Community
- **Persistence:** metadata
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and SHEETS_EMULATOR_HOST
eval "$(localcloud env)"
```

Read a configured lookup range

1. Seed a spreadsheet and an exact A1 range.
2. Request that range with values.get or values.batchGet.
3. Check the returned rows in the consuming application.

### Documented workflows

- Exact A1-range reads: values.get and values.batchGet

### Service boundaries

- Read-only auxiliary fixture API
- No spreadsheet metadata, writes, range slicing, or formulas
- No Google OAuth authority

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Google Sheets with an AI agent

Before the agent changes application logic, have it create local Google Sheets state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Google Sheets documentation](https://developers.google.com/workspace/sheets/api/guides/concepts): service concepts and cloud usage.

---

## Memorystore (Redis/Valkey)

> Run Memorystore (Redis/Valkey) locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/memorystore/

Memorystore provides managed in-memory data services on Google Cloud. LocalCloud uses a Valkey runtime for documented Redis-compatible commands and instance metadata.

### Typical uses

Use when frequently accessed values, expiring entries, counters, or streams fit Redis commands and an in-memory access model. Choose key names and expiries around the application's cache or queue behavior.

Examples

- Application caches and counters
- Redis-compatible queues and streams

Databases

Connection

Environment variable

`REDIS_HOST=localhost:5390`

Runtime details

- **Endpoints:** RESP :5390
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Third-Party Emulator

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and REDIS_HOST
eval "$(localcloud env)"
```

Test a cache hit and expiry

1. Connect a Redis-compatible client to the local endpoint.
2. SET a test key with an expiry and GET its value.
3. Verify the cache-miss path after the key expires.

### Documented workflows

- Valkey RESP, Lua, Pub/Sub, streams, and transactions
- Redis instance lifecycle, configuration, version labels, and AUTH retrieval

### Service boundaries

- Shared server; database numbers do not isolate Pub/Sub channels
- No multi-shard topology, managed failover, or project authorization

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Memorystore (Redis/Valkey) with an AI agent

Before the agent changes application logic, have it create local Memorystore (Redis/Valkey) state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Memorystore (Redis/Valkey) documentation](https://docs.cloud.google.com/memorystore/docs/redis/memorystore-for-redis-overview): service concepts and cloud usage.

---

## Pub/Sub emulator

> Run Pub/Sub locally: topics, subscriptions, push and pull delivery, acknowledgements, dead-letter retries, and schemas on port 5383.
>
> Source: https://local.cloud/services/pubsub/

Pub/Sub is asynchronous messaging between publishers and subscribers. Topics decouple event producers from the applications that process those events.

### Typical uses

Use when several consumers need to react to the same event independently of its publisher. Consumers acknowledge completed work and handle retries without blocking the producer.

Examples

- Event-driven application pipelines
- Background processing and fan-out

Messaging & Workflow

Connection

Environment variable

`PUBSUB_EMULATOR_HOST=localhost:5383`

Runtime details

- **Endpoints:** gRPC :5383
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Hello world

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and PUBSUB_EMULATOR_HOST
eval "$(localcloud env)"
```

Python

#### Publish and acknowledge a message

2\. Install SDK · shell

```
python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-pubsub
```

3\. Save as hello.py

```
import os
from uuid import uuid4
from google.cloud import pubsub_v1

assert os.environ['PUBSUB_EMULATOR_HOST']
project = os.environ['GOOGLE_CLOUD_PROJECT']
publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
name = 'hello-' + uuid4().hex[:12]
topic = publisher.topic_path(project, name)
subscription = subscriber.subscription_path(project, name)

publisher.create_topic(request={'name': topic}, timeout=30)
try:
    subscriber.create_subscription(request={'name': subscription, 'topic': topic}, timeout=30)
    try:
        publisher.publish(topic, b'Hello, Pub/Sub!').result(timeout=30)
        response = subscriber.pull(request={'subscription': subscription, 'max_messages': 1}, timeout=30)
        assert response.received_messages
        for received in response.received_messages:
            print(received.message.data.decode())
            subscriber.acknowledge(request={'subscription': subscription, 'ack_ids': [received.ack_id]}, timeout=30)
    finally:
        subscriber.delete_subscription(request={'subscription': subscription}, timeout=30)
finally:
    publisher.delete_topic(request={'topic': topic}, timeout=30)
    subscriber.close()
    publisher.transport.close()
```

4\. Run`python hello.py`

[Full example guide](https://local.cloud/docs/sdk-examples/#pubsub-python)

### Documented workflows

- Topics, subscriptions, push/pull, StreamingPull, and acknowledgements
- Attribute filters, dead-letter forwarding, and retries
- Retention, snapshots, and timestamp/snapshot seek
- Avro/Protobuf schemas, revisions, and JSON/binary validation
- Authenticated push with locally signed OIDC tokens

### Service boundaries

- No exactly-once delivery, exports, transforms, or push payload wrappers
- Push receivers must trust LocalCloud's issuer and JWKS; validate delivery with your application
- Approximate local retry and retention schedules
- Stored IAM bindings do not enforce publish or topic deletion

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.
- [Official SDK code samples](https://docs.cloud.google.com/pubsub/docs/samples): Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Agent testing

### Use Pub/Sub with an AI agent

Before the agent changes application logic, have it create local Pub/Sub state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Pub/Sub local test

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Pub/Sub emulator FAQ

#### How do I run Pub/Sub locally?

Install the LocalCloud CLI, start the runtime, and export its environment, as in the example above.

#### Which environment variable points the SDK at the local Pub/Sub?

LocalCloud exports PUBSUB\_EMULATOR\_HOST=localhost:5383. Use the generated value, because the CLI picks another port when the default is in use. Some SDKs also need explicit client endpoint options; the variable alone does not route them locally.

#### Does the local Pub/Sub behave exactly like Google Cloud?

No. LocalCloud runs the documented workflows on this page within the service boundaries listed here. Validate behavior against real Pub/Sub before production deployment.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Pub/Sub documentation](https://docs.cloud.google.com/pubsub/docs/overview): service concepts and cloud usage.

---

## Secret Manager

> Run Secret Manager locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/secret-manager/

Secret Manager stores versioned sensitive values such as API keys and passwords. Applications retrieve a chosen secret version instead of embedding values in source code.

### Typical uses

Use when applications retrieve credentials or sensitive configuration at runtime, and values need versioning or rotation independently of an application release.

Examples

- Application configuration secrets
- Versioned credential rollouts

Security

Connection

Environment variable

`SECRET_MANAGER_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and SECRET_MANAGER_EMULATOR_HOST
eval "$(localcloud env)"
```

Load a versioned application secret

1. Create a secret containing a fake local value.
2. Add a version and retrieve its payload.
3. Disable that version and verify the application handles the failure.

### Documented workflows

- Secret CRUD
- Version add/access/list/enable/disable/destroy
- SOFTWARE CMEK encryption and per-secret IAM policy APIs

### Service boundaries

- No automatic rotation notifications or topic delivery
- Authorization varies by transport and IAM mode
- Hardware key custody and geographic replication are cloud-only

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Provision resources with Terraform](https://local.cloud/docs/terraform/#supported-terraform-resources): Documented resources, provider configuration, and local routing setup.
- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.
- [Official SDK code samples](https://docs.cloud.google.com/secret-manager/docs/samples): Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Agent testing

### Use Secret Manager with an AI agent

Before the agent changes application logic, have it create local Secret Manager state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Secret Manager documentation](https://docs.cloud.google.com/secret-manager/docs/overview): service concepts and cloud usage.

---

## Service Usage

> Run Service Usage locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/service-usage/

Service Usage manages which Google APIs and services are enabled for a project. LocalCloud supplies the documented preflight responses used by provisioning clients.

### Typical uses

Use when provisioning clients check API availability or request service enablement before creating resources. Local preflight responses let you exercise those client flows.

Examples

- API enablement preflight checks
- Provisioning-client compatibility tests

Operations

Connection

Environment variable

`SERVICE_USAGE_EMULATOR_HOST=http://localhost:5380`

Runtime details

- **Endpoints:** HTTP/REST :5380
- **Minimum tier:** Community
- **Persistence:** stateless
- **Implementation:** Local Facade

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Local workflow

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and SERVICE_USAGE_EMULATOR_HOST
eval "$(localcloud env)"
```

Test an API enablement preflight

1. Request enablement for a service through the local facade.
2. Poll the returned operation.
3. Verify the response without treating it as runtime service activation.

### Documented workflows

- Service list/get/enable/batchEnable preflights and completed operation polling

### Service boundaries

- Reports ENABLED; runtime activation uses LocalCloud service controls
- No quota enforcement, billing, or project-specific entitlement

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

### Use Service Usage with an AI agent

Before the agent changes application logic, have it create local Service Usage state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Service Usage documentation](https://docs.cloud.google.com/service-usage/docs/overview): service concepts and cloud usage.

---

## Spanner emulator

> Run Spanner locally: GoogleSQL and PostgreSQL queries, transactions, graph and vector search, and administration on ports 5386 and 5387.
>
> Source: https://local.cloud/services/spanner/

Spanner is a distributed database with SQL and transactional consistency. Use its relational model when application workflows need coordinated updates across related records.

### Typical uses

Use when related records need transactional consistency and SQL queries, and your production architecture requires a database that can scale across nodes.

Examples

- Transactional order and inventory systems
- Relational applications using GoogleSQL or PostgreSQL

Databases

Connection

Environment variable

`SPANNER_EMULATOR_HOST=localhost:5386`

Runtime details

- **Endpoints:** gRPC :5386 · HTTP/REST :5387
- **Minimum tier:** [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier)
- **Persistence:** service-data
- **Implementation:** Extended Official

Use `localcloud env` for the current endpoints; if a default port is already in use, the CLI picks another one.

Hello world

### Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1\. Install and start · shell

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and SPANNER_EMULATOR_HOST
eval "$(localcloud env)"
```

Python

#### Create a database and query a row

2\. Install SDK · shell

```
python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-spanner
```

3\. Save as hello.py

```
import os
from uuid import uuid4
from google.cloud import spanner

assert os.environ['SPANNER_EMULATOR_HOST']
client = spanner.Client(project=os.environ['GOOGLE_CLOUD_PROJECT'])
instance = client.instance('guide-' + uuid4().hex[:12], configuration_name='projects/' + client.project + '/instanceConfigs/emulator-config', display_name='Guide', node_count=1)
instance.create().result(timeout=60)
try:
    database = instance.database('messages', ddl_statements=['CREATE TABLE Messages (Id INT64 NOT NULL, Message STRING(100)) PRIMARY KEY (Id)'])
    database.create().result(timeout=60)
    with database.batch() as batch:
        batch.insert('Messages', columns=('Id', 'Message'), values=[(1, 'hello')])
    with database.snapshot() as snapshot:
        rows = list(snapshot.execute_sql('SELECT Message FROM Messages WHERE Id = 1'))
        assert rows == [['hello']]
        print(rows[0][0])
    database.drop()
finally:
    instance.delete()
    client.close()
```

4\. Run`python hello.py`

[Full example guide](https://local.cloud/docs/sdk-examples/#spanner-python)

### Documented workflows

- GoogleSQL/PostgreSQL queries, UUIDs, and change streams
- Full-text/vector search, property graphs, and graph algorithms
- Sessions, serializable/repeatable-read transactions, and batch DML
- Partitioned queries/reads and batch writes
- Instance/database administration, DDL, and long-running operations
- Database roles and fine-grained access control
- Backup creation, copy, restore, and schedules

### Service boundaries

- Change streams require streaming SQL
- Backups and durable stream recovery require a persistent data directory
- Unauthenticated emulator connections bypass network IAM
- No CMEK; Google TrueTime and regional infrastructure are cloud-only

Try it in your project

### Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.
- [Official SDK code samples](https://docs.cloud.google.com/spanner/docs/samples): Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Agent testing

### Use Spanner with an AI agent

Before the agent changes application logic, have it create local Spanner state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

#### Configure this repo

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

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

### Spanner emulator FAQ

#### How do I run Spanner locally?

Install the LocalCloud CLI, start the runtime, and export its environment, as in the example above.

#### Which environment variable points the SDK at the local Spanner?

LocalCloud exports SPANNER\_EMULATOR\_HOST=localhost:5386. Use the generated value, because the CLI picks another port when the default is in use. Some SDKs also need explicit client endpoint options; the variable alone does not route them locally.

#### Does the local Spanner behave exactly like Google Cloud?

No. LocalCloud runs the documented workflows on this page within the service boundaries listed here. Validate behavior against real Spanner before production deployment.

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Spanner feature reference](https://local.cloud/docs/spanner-emulator-features/): detailed operation and recovery notes.
- [Official Spanner documentation](https://cloud.google.com/spanner): service concepts and cloud usage.

---

## Vertex AI

> Vertex AI doesn't run in LocalCloud yet; local support is planned. Use Google Cloud for Vertex AI and read the official documentation.
>
> Source: https://local.cloud/services/vertex-ai/

Unsupported

Vertex AI provides model development and AI inference APIs on Google Cloud. Local model execution and inference are planned for LocalCloud and are not available yet.

Compute & Runtime

Local availability

### Not available locally

Vertex AI doesn't run in LocalCloud; use Google Cloud for inference and training.

- Local stubs: deterministic responses only
- Inference, embeddings, tokenization: use Google Cloud
- Training, tuning, endpoints, batch prediction: use Google Cloud

[Read the official Vertex AI documentation](https://docs.cloud.google.com/gemini-enterprise-agent-platform/machine-learning)

### Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Official Vertex AI documentation](https://docs.cloud.google.com/gemini-enterprise-agent-platform/machine-learning): service concepts and cloud usage.

---

## LocalCloud comparisons for agents

> Compare LocalCloud with LocalStack, Google's Cloud CLI and Firebase emulators, community emulators and hosted agent sandboxes, with sources for every fact.
>
> Source: https://local.cloud/compare/

Compare

Choose the right local or hosted sandbox by job: service fidelity, arbitrary code isolation, BigQuery-only testing, or multi-service local GCP workflows.

[AI onboarding](https://local.cloud/ai/) [Compatibility](https://local.cloud/compatibility/) [Docs](https://local.cloud/docs/)

Local options for Google Cloud

### LocalCloud, LocalStack and Google's emulators

LocalStack emulates AWS and Snowflake, not Google Cloud; teams on both clouds run both. Google ships separate emulators for Bigtable, Datastore, Firestore, Pub/Sub and Spanner through the Google Cloud CLI, and the Firebase Local Emulator Suite for Firebase products. The Google Cloud CLI has no BigQuery or Cloud Storage emulator. Single-service community emulators typically cover one Google Cloud service each, such as BigQuery or Cloud Storage; coverage and fidelity vary by project. LocalCloud runs 25 Google Cloud services, including BigQuery and Cloud Storage, in one Docker container, using Google's Firestore emulator and a Spanner emulator built from Google's open-source emulator.

Sources reviewed October 5, 2026; each fact about a named product links its source.

|  | LocalCloud | Google Cloud CLI emulators | Firebase Local Emulator Suite | LocalStack | Single-service community emulators |
| --- | --- | --- | --- | --- | --- |
| Google Cloud services | 25 Google Cloud services in one Docker container Source: [Service catalog](https://local.cloud/services/) | Five: Bigtable, Datastore, Firestore, Pub/Sub and Spanner, each started on its own Source: [gcloud beta emulators reference](https://docs.cloud.google.com/sdk/gcloud/reference/beta/emulators) | Firebase products: Firestore, Realtime Database, Cloud Storage for Firebase, Authentication, Hosting, Cloud Functions, Pub/Sub and Extensions Source: [Firebase Local Emulator Suite](https://firebase.google.com/docs/emulator-suite) | None; LocalStack covers AWS and Snowflake Source: [LocalStack pricing](https://www.localstack.cloud/pricing) | Typically one Google Cloud service each, such as BigQuery or Cloud Storage |
| BigQuery and Cloud Storage | Both, alongside Pub/Sub, Spanner, Firestore and the rest of the stack Source: [Compatibility](https://local.cloud/compatibility/) | No BigQuery or Cloud Storage emulator Source: [gcloud beta emulators reference](https://docs.cloud.google.com/sdk/gcloud/reference/beta/emulators) | No BigQuery; Cloud Storage for Firebase only Source: [Firebase Local Emulator Suite](https://firebase.google.com/docs/emulator-suite) | No Source: [LocalStack pricing](https://www.localstack.cloud/pricing) | Separate projects, one per service |
| How services run | Google's Firestore emulator, a Spanner emulator built from Google's open-source emulator, PostgreSQL and MySQL for Cloud SQL, Valkey for Memorystore, and a DuckDB-backed BigQuery Source: [Architecture](https://local.cloud/docs/architecture/) | Google-built emulators installed as Google Cloud CLI components Source: [Install the Google Cloud CLI](https://docs.cloud.google.com/sdk/docs/install-sdk) | Started together by the Firebase CLI Source: [Install and configure the emulators](https://firebase.google.com/docs/emulator-suite/install_and_configure) | One container image for AWS services Source: [LocalStack single-image announcement](https://blog.localstack.cloud/localstack-single-image-next-steps/) | Independent open-source reimplementations; coverage and fidelity vary by project |
| Data across restarts | Stored in a named Docker volume that survives restarts Source: [Architecture](https://local.cloud/docs/architecture/) | Pub/Sub keeps data for the emulator session; the Spanner emulator keeps data in memory only Source: [Pub/Sub emulator](https://docs.cloud.google.com/pubsub/docs/emulator) · [Cloud Spanner emulator](https://github.com/GoogleCloudPlatform/cloud-spanner-emulator) | Export on exit and import on the next start Source: [Install and configure the emulators](https://firebase.google.com/docs/emulator-suite/install_and_configure) | Not applicable to Google Cloud Source: [LocalStack pricing](https://www.localstack.cloud/pricing) | Varies by project |
| License | Proprietary Public Preview License Source: [License](https://local.cloud/license/) | Google tooling; the Spanner emulator is open source (Apache-2.0) Source: [Cloud Spanner emulator](https://github.com/GoogleCloudPlatform/cloud-spanner-emulator) | Open source (MIT) Source: [firebase-tools](https://github.com/firebase/firebase-tools) | Proprietary plans; current releases need an account and auth token since March 23, 2026 Source: [LocalStack single-image announcement](https://blog.localstack.cloud/localstack-single-image-next-steps/) | Open-source licenses that vary by project |
| Cost and sign-up | Free during the public preview, with no account or license key; open-source projects stay free after it Source: [Pricing](https://local.cloud/pricing/) | Installed with the Google Cloud CLI Source: [Install the Google Cloud CLI](https://docs.cloud.google.com/sdk/docs/install-sdk) | Free to use under its open-source license Source: [firebase-tools](https://github.com/firebase/firebase-tools) | Free Hobby plan for non-commercial use; paid plans for commercial use Source: [LocalStack pricing](https://www.localstack.cloud/pricing) | Free |

Reviewed October 5, 2026 against each project's official documentation, pricing page or repository. Plans and features change; follow the source links for current terms.

### Comparisons

Comparison

#### [LocalCloud vs Google emulators for agents](https://local.cloud/compare/google-emulators/)

Compare LocalCloud with Google's official emulators for agent workflows on local Google Cloud, with sources and the cases where Google's emulators fit better.

- Google gcloud emulators include service-specific emulator groups.
- LocalCloud runs 25 local services in one Docker image; Firestore is opt-in, and each service documents its local boundaries.

Comparison

#### [LocalCloud vs hosted agent sandboxes](https://local.cloud/compare/e2b-vercel-sandboxes/)

Compare LocalCloud with hosted code sandboxes such as E2B for agent workflows: where each one fits, and why many agent setups use both.

- E2B and Vercel focus on isolated code execution environments.
- LocalCloud focuses on local Google Cloud APIs and SDK endpoints.

Comparison

#### [BigQuery emulator alternatives for agents](https://local.cloud/compare/bigquery-emulator-alternatives/)

Compare LocalCloud BigQuery with standalone BigQuery emulators and real BigQuery for agent-written pipelines, including when each option fits better.

- LocalCloud BigQuery runs beside Pub/Sub, Storage, Spanner, and other available services.
- Single-service community emulators focus on BigQuery alone; their coverage and fidelity vary by project.

Comparison

#### [LocalStack for Google Cloud](https://local.cloud/localstack-for-google-cloud/)

LocalStack emulates AWS; LocalCloud emulates Google Cloud. When each one fits, how SDK routing differs, and why multi-cloud teams run both.

- LocalStack had no Google Cloud services as of October 5, 2026.
- AWS SDK calls do not reach LocalCloud, and Google Cloud SDK calls do not reach LocalStack.

---

## BigQuery emulator alternatives for agents

> Compare LocalCloud BigQuery with standalone BigQuery emulators and real BigQuery for agent-written pipelines, including when each option fits better.
>
> Source: https://local.cloud/compare/bigquery-emulator-alternatives/

Comparison

Agents writing BigQuery code need fast SQL feedback without surprise query costs. LocalCloud includes a BigQuery surface inside a broader GCP emulator runtime; standalone emulators and real BigQuery can be better depending on fidelity, scope, and deployment risk.

[Read docs](https://local.cloud/docs/) [Check compatibility](https://local.cloud/compatibility/) [SDK examples](https://local.cloud/docs/sdk-examples/)

Fact

LocalCloud BigQuery runs beside Pub/Sub, Storage, Spanner, and other available services.

Fact

Single-service community emulators focus on BigQuery alone; their coverage and fidelity vary by project.

Fact

Real BigQuery remains the source of truth for production behavior.

Where standalone is better

### Choose a focused emulator for narrow BigQuery-only testing

If your workflow only needs a BigQuery-compatible server, a single-service community emulator can be simpler to run. Check its coverage for the queries you depend on.

Where LocalCloud is better

### Choose LocalCloud for agent-written pipelines across services

Agent workflows often pair BigQuery with Pub/Sub events, Cloud Storage objects, seed data, Terraform, and health checks. LocalCloud keeps those pieces in one runtime.

Where real BigQuery is better

### Use real BigQuery for production-critical semantics

Use real BigQuery for billing, IAM, slots, reservations, full GoogleSQL edge cases, performance, geographic behavior, and final release validation.

How to compare

### Test the queries you run, not a feature count

A storage engine, an advertised feature count or a small benchmark can't establish BigQuery compatibility. A fair comparison needs the exact engine revisions, images, query corpus, reference outputs and a replay command; this site has no current comparison that tests the engines and the LocalCloud image together, so it ranks no option on speed or fidelity. Run representative queries through the API your application uses and assert the rows, errors and state changes.

Copy-ready setup

### Commands and prompts

#### Copy a prompt for your coding agent

##### BigQuery local test

Ask an agent to validate BigQuery code against the local emulator.

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

##### Configure this repo

Have an agent wire an existing project to LocalCloud safely.

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

Compatibility

### Local check versus release validation

| Option | Runs as | Best for | Caveat |
| --- | --- | --- | --- |
| LocalCloud BigQuery | Native GoogleSQL analysis with DuckDB execution, supervised inside the LocalCloud Docker container; the default process needs no Docker-socket access. | Multi-service local Google Cloud workflows, free of charge for individuals and companies during the public preview. | Coverage is documented feature by feature; validate release behavior in real BigQuery. |
| Single-service community emulators | An independent open-source server, usually a standalone binary or container; storage, REST and gRPC coverage vary by project. | A focused BigQuery-compatible local server. | A separate runtime from the rest of the GCP workflow; check the project's current feature matrix for the methods you need. |
| Real BigQuery | The managed Google Cloud service, in a Google Cloud project. | Production fidelity and managed features. | Requires credentials, project setup, quotas, and billable usage. |

Production boundary

### Before production

Use LocalCloud for non-production development, testing, and CI under the [Public Preview License](https://local.cloud/license/), check [each service's local boundaries](https://local.cloud/compatibility/), and validate against real Google Cloud before you deploy.

- LocalCloud does not claim full BigQuery production parity.
- Unsupported areas include BQML, AEAD encryption functions, security policy enforcement, and full GEOGRAPHY parity.

Related

### Next steps

- [BigQuery service guide](https://local.cloud/services/bigquery/) — Setup, documented workflows, and a prompt for AI agents.

Sources and review

### Claims are tied to current sources

- [BigQuery emulator feature reference](https://local.cloud/docs/bigquery-emulator-features/) — LocalCloud's operation contract and coverage matrix.
- [Google BigQuery documentation](https://docs.cloud.google.com/bigquery/docs) — The managed service's reference.
- LocalCloud agentic facts reviewed 2026-10-09.

---

## LocalCloud vs hosted agent sandboxes

> Compare LocalCloud with hosted code sandboxes such as E2B for agent workflows: where each one fits, and why many agent setups use both.
>
> Source: https://local.cloud/compare/e2b-vercel-sandboxes/

Comparison

E2B and Vercel Sandbox isolate arbitrary code execution for agents. LocalCloud replaces Google Cloud API calls with localhost emulators for the non-production work its license permits. The products address different boundaries.

[Read docs](https://local.cloud/docs/) [Check compatibility](https://local.cloud/compatibility/) [SDK examples](https://local.cloud/docs/sdk-examples/)

Fact

E2B and Vercel focus on isolated code execution environments.

Fact

LocalCloud focuses on local Google Cloud APIs and SDK endpoints.

Fact

A hosted sandbox may still need LocalCloud or real GCP to exercise GCP-specific behavior.

Where hosted sandboxes are better

### Use E2B or Vercel when the risk is arbitrary code execution

If the primary problem is running untrusted generated code away from your workstation or production systems, hosted sandboxes are purpose-built for that execution boundary.

Where LocalCloud is better

### Use LocalCloud when the risk is accidental cloud side effects

If the agent is writing BigQuery, Pub/Sub, Storage, or Terraform code, LocalCloud gives the code a local GCP-like API target with no default cloud account or billing project.

Copy-ready setup

### Commands and prompts

#### Copy a prompt for your coding agent

##### Start LocalCloud

Give an agent one URL and have it start the local GCP sandbox.

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

##### Configure this repo

Have an agent wire an existing project to LocalCloud safely.

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

Compatibility

### Local check versus release validation

| Need | Hosted code sandbox | LocalCloud |
| --- | --- | --- |
| Run arbitrary generated code | Primary use case. | Not the isolation layer for arbitrary shell risk. |
| Exercise GCP SDK calls | Needs external target or real cloud. | Primary use case through localhost endpoints. |
| Avoid GCP credentials by default | Depends on what the sandboxed code calls. | Default LocalCloud workflows need no GCP credentials. |

Production boundary

### Before production

Use LocalCloud for non-production development, testing, and CI under the [Public Preview License](https://local.cloud/license/), check [each service's local boundaries](https://local.cloud/compatibility/), and validate against real Google Cloud before you deploy.

- LocalCloud does not replace a hosted code-execution sandbox for untrusted shell workloads.

Related

### Next steps

- [Agent pages](https://local.cloud/agents/) — Use LocalCloud with terminal and IDE agents.

Sources and review

### Claims are tied to current sources

- [E2B documentation](https://www.e2b.dev/docs) — E2B describes isolated sandboxes for agents to execute code.
- [Vercel Sandbox docs](https://vercel.com/docs/sandbox) — Vercel describes isolated ephemeral Linux VMs for agent and code workloads.
- LocalCloud agentic facts reviewed 2026-10-09.

---

## LocalCloud vs Google emulators for agents

> Compare LocalCloud with Google's official emulators for agent workflows on local Google Cloud, with sources and the cases where Google's emulators fit better.
>
> Source: https://local.cloud/compare/google-emulators/

Comparison

Google official emulators are the best source when your target service has one and you want the closest Google-maintained local surface. LocalCloud is the broader agent runtime when one workflow needs many GCP-like services, shared health, seed data, and one container.

[Read docs](https://local.cloud/docs/) [Check compatibility](https://local.cloud/compatibility/) [SDK examples](https://local.cloud/docs/sdk-examples/)

Fact

Google gcloud emulators include service-specific emulator groups.

Fact

LocalCloud runs 25 local services in one Docker image; Firestore is opt-in, and each service documents its local boundaries.

Fact

Neither path removes the need for real-GCP validation before production.

Where Google is better

### Use official emulators for service-specific fidelity

If a single supported official emulator covers your exact service and feature set, it may be the right lowest-risk local dependency. Choose it when:

- It covers the one service and operation you need.
- Following Google's release and compatibility model matters more than a shared multi-service runtime.
- You don't need a shared health check, environment export, seed data, console or cross-service operator routes.

Where LocalCloud is better

### Use LocalCloud for multi-service agent workflows

Count the workflow, not just the services: an agent needs startup, health, environment export, seed data, logs, docs and a clear failure boundary. LocalCloud packages that surface with one start command, one health check and a service catalog that includes services without official Google emulators, such as BigQuery and Cloud Storage. Choose it when:

- One workflow needs several Google Cloud services in one runtime.
- You want one service catalog with operation-level status for every service.
- The CLI's generated endpoints and shared operator routes simplify the local workflow.

Copy-ready setup

### Commands and prompts

#### Copy a prompt for your coding agent

##### Start LocalCloud

Give an agent one URL and have it start the local GCP sandbox.

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

##### Configure this repo

Have an agent wire an existing project to LocalCloud safely.

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

Google's emulators: one process per service

```
# Pub/Sub
gcloud components install pubsub-emulator
gcloud beta emulators pubsub start --host-port=localhost:5383

# Firestore
gcloud beta emulators firestore start --host-port=localhost:5384

# Spanner
gcloud components install spanner-emulator
gcloud emulators spanner start --host-port=localhost:5386
```

LocalCloud: one runtime for every service

```
curl -fsSL https://local.cloud/install.sh | sh
localcloud doctor
localcloud start --local-only
curl -fsS http://localhost:5380/readiness
eval "$(localcloud env)"
localcloud console

# Use the endpoint values the CLI returns; it picks another port when a default one is in use.
```

Comparison prompt

```
Compare this repository's GCP usage with LocalCloud service coverage and Google official emulator availability. Recommend the smallest local validation path and list real-GCP checks that must remain.
```

Compatibility

### Local check versus release validation

| Decision point | Google emulators | LocalCloud |
| --- | --- | --- |
| Scope | Individual emulator groups managed through gcloud or service-specific images. | A catalog of operation-specific guides through one LocalCloud runtime entry point. |
| Agent setup | Per-service install, command, ports, and env init. | One Docker image, health endpoint, and shell env export. |
| Best fit | Single-service fidelity where Google ships an emulator. | Multi-service testing, demos, and agent discovery. Individuals and companies can use it free of charge for non-production work during the public preview. |

Production boundary

### Before production

Use LocalCloud for non-production development, testing, and CI under the [Public Preview License](https://local.cloud/license/), check [each service's local boundaries](https://local.cloud/compatibility/), and validate against real Google Cloud before you deploy.

Related

### Next steps

- [GCP emulator overview](https://local.cloud/gcp-emulator/) — LocalCloud positioning against fragmented GCP local development.
- [Compatibility](https://local.cloud/compatibility/) — Current LocalCloud service boundaries.

Sources and review

### Claims are tied to current sources

- [gcloud beta emulators reference](https://docs.cloud.google.com/sdk/gcloud/reference/beta/emulators) — Google emulator command groups.
- LocalCloud agentic facts reviewed 2026-10-09.