Run Google Cloud Platform services entirely on your machine.
No real GCP credentials. No network. No billing surprises.
Like LocalStack, but purpose-built for Google Cloud.
Develop and test against real-looking GCP APIs without a Google account, billing, or service account keys.
Works with the official google-cloud-* Python SDKs. Point them at Cloudbox and your code runs unchanged.
All services start in under a second. No Docker images to pull, no network calls, no cold-start delays.
FastAPI + uvicorn. Easy to inspect, extend, and debug. DuckDB powers BigQuery and Spanner queries.
Built-in web dashboard at localhost:8888 — browse buckets, topics, secrets, and tasks in real time.
In-memory by default. Set CLOUDBOX_DATA_DIR to persist state across restarts via atomic JSON writes.
Each service runs as an independent FastAPI server started concurrently from a single entry point.
Buckets, objects, simple / multipart / resumable uploads, notifications, lifecycle rules, gsutil-compatible CLI.
:4443 · RESTTopics, subscriptions, push & pull, dead-letter, message filters, ordering, snapshots, schema validation.
:8085 gRPC · :8086 RESTDocuments, collections, structured queries, composite filters, transactions, field masks, batch get.
:8080 · RESTSecrets, versioned payloads, enable / disable / destroy, latest resolution, cascading deletes.
Queues, HTTP tasks, deferred scheduling, retry on failure, force-run, auto-dispatch background worker.
:8123 · RESTDatasets, tables, SELECT / DML, streaming inserts, async jobs, CTAS — backed by DuckDB.
:9050 · RESTInstances, databases, DDL, sessions, mutations, SQL & streaming reads — backed by DuckDB.
:9010 · RESTLog entries, severity & timestamp filters, sinks, log-based metrics, Cloud Monitoring time series.
:9020 · RESTCron jobs, HTTP targets, pause / resume, force-run, background dispatch worker via croniter.
Pull from Docker Hub, compose from source, or run locally with uv.
Pull and run the published image directly — no clone needed:
docker run -p 4443:4443 -p 8080:8080 \
-p 8085:8085 -p 8086:8086 \
-p 8090:8090 -p 8123:8123 \
-p 9050:9050 -p 9010:9010 \
-p 9020:9020 -p 8091:8091 \
-p 8888:8888 \
omab/cloudbox:latestAdmin UI → http://localhost:8888
Clone the repo and start all services with one command:
git clone https://github.com/omab/cloudbox
cd cloudbox
docker compose upAdmin UI → http://localhost:8888
Requires Python 3.12+ and uv.
git clone https://github.com/omab/cloudbox
cd cloudbox
uv sync
uv run cloudboxInstall the package and run it directly:
pip install cloudbox
cloudboxPoint the google-cloud-* libraries at Cloudbox — your application code stays identical.
from google.cloud import storage
from google.auth.credentials import AnonymousCredentials
client = storage.Client(
project="local-project",
client_options={"api_endpoint": "http://localhost:4443"},
credentials=AnonymousCredentials(),
)
bucket = client.bucket("my-bucket")# gRPC — set env var before importing the SDK
import os
os.environ["PUBSUB_EMULATOR_HOST"] = "localhost:8085"
from google.cloud import pubsub_v1
publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path("local-project", "my-topic")
publisher.create_topic(name=topic_path)from google.cloud import bigquery
from google.auth.credentials import AnonymousCredentials
client = bigquery.Client(
project="local-project",
client_options={"api_endpoint": "http://localhost:9050"},
credentials=AnonymousCredentials(),
)
for row in client.query("SELECT 1 AS n").result():
print(row.n)from google.cloud import secretmanager
from google.auth.credentials import AnonymousCredentials
client = secretmanager.SecretManagerServiceClient(
client_options={"api_endpoint": "localhost:8090"},
credentials=AnonymousCredentials(),
)
secret = client.create_secret(
request={
"parent": "projects/local-project",
"secret_id": "api-key",
"secret": {},
}
)
Pre-configured helpers for all services are in sdk_compat/clients.py.
Two CLI entry points installed by uv sync — use your existing shell scripts unchanged.
gsutillocal ls # list buckets
gsutillocal ls gs://my-bucket # list objects
gsutillocal mb gs://my-bucket # create bucket
gsutillocal cp ./file.txt gs://b/f # upload
gsutillocal cp gs://b/f ./file.txt # download
gsutillocal cp gs://b1/o gs://b2/o # copy between buckets
gsutillocal mv gs://b/old gs://b/new # move / rename
gsutillocal rm gs://b/logs/* # wildcard delete
gsutillocal stat gs://b/file.txt # object metadatagcloudlocal pubsub topics create my-topic
gcloudlocal pubsub subscriptions create my-sub \
--topic my-topic
gcloudlocal pubsub topics publish my-topic \
--message "hello world"
gcloudlocal secrets create api-key
gcloudlocal secrets versions add api-key --data "s3cr3t"
gcloudlocal tasks queues create my-queue
gcloudlocal scheduler jobs list