# How to run Google Cloud services locally

> Install the LocalCloud CLI, start a localhost-only runtime, and connect your code to 25 local Google Cloud services.
>
> Source: https://local.cloud/how-to-run-google-cloud-locally/

Complete Guide

Install the CLI, start a runtime that listens only on localhost, and check what each service supports.

[Quick start](https://local.cloud/how-to-run-google-cloud-locally/#quick-start) [Full documentation](https://local.cloud/docs/)

## 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 request path

Supported requests target localhost endpoints. Review the governing license before use and stop rather than falling back to real Google Cloud.

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](https://local.cloud/services/), or check [compatibility](https://local.cloud/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.

[Install Docker →](https://docs.docker.com/get-docker/)

2

### Install the CLI

Use the checksum-verifying installer on a supported macOS or Linux host:

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

3

### 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/readiness
```

Use 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 status
```

## Service-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.](https://local.cloud/services/bigquery/)[Cloud Storage Run bucket and object workflows backed by the LocalCloud volume.](https://local.cloud/services/cloud-storage/)[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.](https://local.cloud/services/firestore/)[Pub/Sub Use documented topic, subscription, publish, pull, and acknowledgement workflows; state is stored in PostgreSQL under the mounted data volume.](https://local.cloud/services/pubsub/)[Spanner Use 8 documented Spanner data and administration workflows over gRPC and REST.](https://local.cloud/services/spanner/)[Bigtable Use documented Bigtable data, administration, persistence, and query workflows.](https://local.cloud/services/bigtable/)

## 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](https://local.cloud/gcp-integration-testing/) 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](https://local.cloud/docs/seed-data/).

### Know each service's limits

Read the [compatibility matrix](https://local.cloud/compatibility/) 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.

[Browse services](https://local.cloud/services/) [Read the docs](https://local.cloud/docs/)