LocalCloud LocalCloud Google Cloud in-a-box
Documentation / Getting Started
Service Catalog GitHub
Browse documentation What is a GCP Emulator?
Getting Started What is a GCP Emulator?

What is a 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
  • bounded 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 selected data-volume runtime:

localcloud start
eval "$(localcloud env)"

The CLI can remap occupied host ports, so do not replace returned values with canonical ports. If a client tries to contact real Google Cloud, stop rather than adding real credentials.

LocalCloud implementation types

TypeMeaning in LocalCloud
External emulatorA separate process supervised inside the container, such as Pub/Sub, Firestore, BigQuery, Bigtable, Spanner, Cloud Storage, or Valkey.
Extended emulatorAn upstream-derived artifact with local additions; the source revision and assembled image must be qualified together.
Local facadeGateway implementation of bounded REST/gRPC workflows backed by local stores or processes.
Operator surfaceRoot routes such as /health, /services, /env, /seed, and /terraform/readiness; these are not Google Cloud APIs.

Spanner REST port 24086 is not PostgreSQL wire and LocalCloud does not package PGAdapter. BigQuery is DuckDB-backed with feature-specific partial behavior. Bigtable extended features remain release-unverified until immutable dependency and assembled-image provenance are resolved.

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 unsupported or release-unverified operation.

Maintained by LocalCloud