localcloud is cloud for agents.

Select the project and services

For a new example directory, save this as localcloud.yaml before starting. In an existing repository, merge the relevant settings into its configuration. This example selects BigQuery, Cloud Storage, and Pub/Sub; adapt the exact service IDs to your project.

localcloud.yaml

version: 1
context:
  project: local-gcp-project
services:
  enabled:
    - bigquery
    - gcs
    - pubsub

Expected result: The configuration includes every service your application needs. Firestore, GKE, and Cloud Run are opt-in.

Start or reuse the local runtime

Run from the configured directory. Start waits for readiness and can reuse the matching runtime. Export its actual mapped endpoints in the same shell or test runner that launches your SDK; do not assume the default ports are available.

setup.sh

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

Expected result: Startup succeeds and the SDK environment points to the selected local runtime. Inspect localcloud status --verbose if startup or endpoint discovery fails.

Verify a local SDK call

Python · BigQuery. Install the client in an isolated environment, save this file, then execute a constant query through the generated local endpoint. This verifies SDK routing without creating persistent resources.

SDK dependencies

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

assert_query.py

# First export endpoints: eval "$(localcloud env)"
import os
from google.auth.credentials import AnonymousCredentials
from google.cloud import bigquery

with bigquery.Client(
    project=os.environ["GOOGLE_CLOUD_PROJECT"],
    credentials=AnonymousCredentials(),
    client_options={"api_endpoint": os.environ["BIGQUERY_EMULATOR_HOST"]},
) as client:
    rows = list(client.query("SELECT 1 AS ok").result(timeout=30))
    assert rows[0].ok == 1
    print("ok=1")

Run the example

python assert_query.py

Expected result: The assertion passes, the command prints ok=1, and no test resources need cleanup.