Sign inSign up

agentcloud/localcloud

By agentcloud

•Updated 6 days ago

Local Google Cloud Dev Env. for BigQuery, Spanner, Pub/Sub, Dataproc, and more with MCP and UI

Image
0

10K+

agentcloud/localcloud repository overview

⁠LocalCloud

Complete local Google Cloud runtime and emulator suite in a single Docker container.

Docker Pulls Image Size Platform

LocalCloud provides a local development and testing environment for Google Cloud Platform (GCP). It enables developers and CI/CD pipelines to build, test, and debug cloud applications entirely offline without incurring cloud costs, configuring IAM service accounts, or managing disparate emulator instances.


⁠Key Features

  • 27 Google Cloud Services in One Image: Storage, BigQuery, Spanner, Pub/Sub, Cloud SQL (PostgreSQL & MySQL), Bigtable, Firestore, Secret Manager, Cloud Tasks, and more.
  • Built-in Web Console: Interactive management UI at http://localhost:5380 for querying tables, inspecting buckets, viewing topics, and managing resources.
  • AI Agent-Native (MCP): Native Model Context Protocol endpoint at /mcp for direct integration with Cursor, Claude Code, Antigravity, and AI coding assistants.
  • Native SDK & Tool Compatibility: Works directly with official Google Cloud client libraries (Python, Go, Node.js, Java), gcloud, gsutil, and Terraform.
  • Fast Startup & Durable Persistence: Starts in seconds with optional host-volume persistence (/var/lib/localcloud) and automated data seeding.
  • Multi-Architecture: Native pre-built images for both linux/amd64 and linux/arm64 (Apple Silicon).

⁠Quick Start

⁠1. Run with Docker

Start the container and publish the service gateway and emulator ports:

docker run -d --name localcloud \
  -p 5380-5405:5380-5405 \
  -v localcloud-data:/var/lib/localcloud \
  agentcloud/localcloud:latest

Open the web console at http://localhost:5380⁠.

⁠2. Connect Your Application

Point standard Google Cloud client SDKs to the local runtime via standard environment variables:

# Cloud Storage
export STORAGE_EMULATOR_HOST="http://localhost:5382"

# Cloud Pub/Sub
export PUBSUB_EMULATOR_HOST="localhost:5383"

# BigQuery
export BIGQUERY_EMULATOR_HOST="http://localhost:5388"

# Cloud Spanner
export SPANNER_EMULATOR_HOST="localhost:5386"

# Cloud Bigtable
export BIGTABLE_EMULATOR_HOST="localhost:5385"

# Firestore
export FIRESTORE_EMULATOR_HOST="localhost:5384"

# Secret Manager
export SECRET_MANAGER_EMULATOR_HOST="localhost:5380"
⁠3. Using with the LocalCloud CLI (lc)

For automatic port management, workspace detection, and transparent DNS:

# Install via Homebrew
brew install LocalGCloud/tap/localcloud

# Start LocalCloud
lc start

⁠Image Variants & Tags

TagVariantDescription
latestFull (default)Complete runtime including BigQuery ML, JavaScript UDFs, external queries, and k3d for real GKE clusters.
liteLiteLightweight footprint (~355 MB) optimized for fast CI/CD and everyday local development without ML models.
0.1.16VersionedStable tagged release builds (<version> and <version>-lite).

⁠Supported Services

ServiceProtocolDefault PortClient Environment Variable
Cloud StorageREST / XML5382STORAGE_EMULATOR_HOST
Cloud Pub/SubgRPC5383PUBSUB_EMULATOR_HOST
Cloud SpannergRPC / REST5386 / 5387SPANNER_EMULATOR_HOST
BigQueryREST / gRPC5388 / 5389BIGQUERY_EMULATOR_HOST
Cloud SQL (Postgres / MySQL)Native5391 / 5406CLOUD_SQL_EMULATOR_HOST
Cloud BigtablegRPC5385BIGTABLE_EMULATOR_HOST
FirestoregRPC / REST5384FIRESTORE_EMULATOR_HOST
Memorystore (Redis/Valkey)Redis5390REDIS_HOST
Secret ManagergRPC5380SECRET_MANAGER_EMULATOR_HOST
Cloud TasksgRPC5380CLOUD_TASKS_EMULATOR_HOST
Cloud SchedulergRPC / REST5380CLOUD_SCHEDULER_EMULATOR_HOST
Cloud Functions (2nd Gen)gRPC5380CLOUD_FUNCTIONS_EMULATOR_HOST
Dataproc (Spark/Hadoop)gRPC5380DATAPROC_EMULATOR_HOST
Cloud KMSgRPC / REST5380CLOUD_KMS_EMULATOR_HOST
AlloyDBgRPC5380ALLOYDB_EMULATOR_HOST
Google Sheets APIREST5380SHEETS_EMULATOR_HOST
Cloud IAM & Resource MgrgRPC / REST5380IAM_EMULATOR_HOST
Cloud Logging & MonitoringgRPC5380CLOUD_LOGGING_EMULATOR_HOST
GKE / Cloud Run / WorkflowsREST / gRPC5380Gateway routes

⁠AI Agent Integration (MCP)

LocalCloud exposes a built-in Model Context Protocol (MCP) server on port 5380:

# Connect any MCP-enabled agent directly to:
http://localhost:5380/mcp

Or configure Cursor / Claude Code / Antigravity with headers:

{
  "mcpServers": {
    "localcloud": {
      "url": "http://127.0.0.1:5380/mcp",
      "headers": {
        "X-LocalCloud-Project": "my-project",
        "X-LocalCloud-User": "developer"
      }
    }
  }
}

⁠Data Seeding & Persistence

Mount a persistent volume to preserve state across restarts:

-v localcloud-data:/var/lib/localcloud

To pre-load schemas, buckets, tables, or seed data at container startup, pass a seed file:

-e LOCALCLOUD_SEED_FILE=/seed.yaml -v ./seed.yaml:/seed.yaml:ro

Or trigger dynamic reseeding via the operator API:

curl -X POST http://localhost:5380/seed -H "Content-Type: application/yaml" --data-binary @seed.yaml

⁠Documentation & Community

Tag summary

Content type

Image

Digest

sha256:33622d532…

Size

483.6 MB

Last updated

6 days ago

docker pull agentcloud/localcloud