LocalLocal request path
Supported requests target localhost endpoints. Review the governing license before use and stop rather than falling back to real Google Cloud.
Complete Guide
How to run Google Cloud services locally
Install the CLI, start a runtime that listens only on localhost, and check what each service supports.
Why run Google Cloud services locally?
Local emulation provides a controlled inner loop for supported workflows. It does not reproduce production latency, IAM, quotas, or every Google Cloud behavior.
Local feedback loop
Local behavior depends on host resources and is not a production performance benchmark.
Offline use
After the image is downloaded, core local workflows can run offline. Telemetry and other configured features can still make outbound requests.
Managed lifecycle
The CLI selects a Docker data volume, manages a runtime that listens only on localhost, and exports its endpoints. Organization use must comply with the proprietary license.
What Google Cloud services can run locally?
LocalCloud runs 25 local services in one managed container, grouped as Databases, Messaging & Workflow, Compute & Runtime, Security, Operations, Storage, Analytics, and Auxiliary Integration APIs. Each service guide lists its workflows, whether it starts by default, and its limits.
Browse all 27 service guides, or check compatibility for operation-level detail. Firestore is opt-in; Google Sheets is a read-only values API for exact A1 ranges. Run eval "$(localcloud env)" for the ports and environment variables of your running runtime.
Step-by-step setup guide
1
Install Docker
Install Docker Desktop (Mac/Windows) or Docker Engine (Linux). LocalCloud requires Docker to run the emulator container.
2
Install the CLI
Use the checksum-verifying installer on a supported macOS or Linux host:
curl -fsSL https://local.cloud/install.sh | sh3
Diagnose and start
The CLI keeps Docker under your control and starts a persistent runtime that listens only on localhost, then the readiness check confirms it is up:
localcloud doctor
localcloud start --local-only
curl -fsS http://localhost:5380/readinessUse the URL and endpoint map in the output. If a default port is already in use, the CLI picks another one; use the endpoint values it returns.
4
Configure and inspect
Export the local endpoints into the shell that starts your application, then open the console:
eval "$(localcloud env)"
localcloud console
localcloud statusService-specific setup guides
Each GCP service has unique configuration and SDK patterns. Follow these guides for service-specific setup instructions.
BigQuery
Develop documented DuckDB-backed dataset, table, query, scripting, and API workflows.
Cloud Storage
Run bucket and object workflows backed by the LocalCloud volume.
Firestore
Firestore runs documented local document and query workflows and is opt-in. Validate transactions, listeners, security rules, and recovery with the exact image you run.
Pub/Sub
Use documented topic, subscription, publish, pull, and acknowledgement workflows; state is stored in PostgreSQL under the mounted data volume.
Spanner
Use 8 documented Spanner data and administration workflows over gRPC and REST.
Bigtable
Use documented Bigtable data, administration, persistence, and query workflows.
Automating an internal development project
The Public Preview License permits individuals and organizations, including for-profit companies, to use containerized automation for ongoing internal development, testing, and CI.
Keep automation inside the preview boundary
For permitted internal automation, pin the image, wait on /readiness, export values from the running LocalCloud runtime, and stop rather than falling back to real Google Cloud. Customer-facing production use remains outside the preview grant.
See the automation eligibility and integration guide before using a hosted runner.
Best practices for local cloud development
Keep local and production settings apart
Set emulator variables only in local and CI environments, so local development never reaches production APIs by accident.
# .env.local
BIGQUERY_EMULATOR_HOST=http://localhost:5388
STORAGE_EMULATOR_HOST=http://localhost:5382
# .env.production
# (no emulator variables — uses real GCP)Seed test data from version control
Keep fixtures in the repository and load them the same way on every run, so supported tests repeat. Seed support is service-specific; see seed data.
Know each service's limits
Read the compatibility matrix before relying on a local result, test edge cases against real Google Cloud in a staging environment that mirrors production, and watch for behavior differences.
Don't benchmark locally
Local emulators perform differently from managed services. Don't infer production latency, throughput or capacity from local runs; load test against real Google Cloud before launch.
Give the team one setup
Pin the reviewed image and check the LocalCloud configuration into version control, so every developer and CI job runs the same setup. Document the one-command start in the README. The Public Preview License covers team and organization use for non-production development, testing, and internal CI.
Frequently asked questions
Do I need to change my application code?
It depends on the client. Many workflows use standard Google Cloud clients once localcloud env sets the emulator endpoints; compatibility varies by service and client. If a client tries to reach real Google Cloud, stop and fix the configuration.
Can I run this in CI/CD pipelines?
Yes. The Public Preview License permits non-production internal CI for individuals and organizations, including for-profit companies. Review the license and test the exact runner before use.
How is LocalCloud licensed?
The proprietary Public Preview License permits individuals and organizations, including for-profit companies, to use LocalCloud free of charge for non-production development, testing, CI, evaluation, and internal pilots. Pro-tier services are included free during the preview.
Start running GCP services locally
One persistent runtime, 25 local services, and documented limits for each.