Learn Architecture

Architecture

LocalCloud packages a Java gateway, the web console, local facades, and external emulator processes in one Docker container. “One container” does not mean every service shares the same protocol, process, storage engine, or compatibility level.

Request flow

localcloud start selects a Docker data volume, discovers or creates one compatible loopback-bound runtime, and may remap occupied canonical ports.
localcloud env resolves that runtime and returns endpoint values for the selected project and caller.
SDK, REST, gRPC, and Terraform requests reach a direct emulator port or the gateway on canonical container port 24080.
The gateway handles operator routes and routes facade/API traffic to local implementations.

Runtime identity and ownership

The named Docker volume mounted at /var/lib/localcloud is the only durable runtime selector; the default is localcloud-data. The CLI verifies the configured image and selects the unique compatible container using that volume. Immutable container ID is live process identity. A recorded ID is only a revalidated tie-break hint.

CLI-created container, network, and volume resources carry exact ownership labels. Ownership is independent per resource. The CLI can start, stop, restart, inspect, and use an attached compatible container, but it never removes or relabels a Docker resource it does not own. Ambiguous volume use, incompatible images, invalid labels, and shared-volume conflicts fail before mutation. Full reset --all-projects requires a fully managed runtime.

Root operator routes include /health, /health/{service}, /readiness, /env, /services, /seed, /reseed, /import, /reset, /terraform/readiness, /graphql, /api-docs, and /docs.

Process and storage model

Component	Current implementation	Persistence boundary
Gateway and local facades	Java/Armeria services	Many facade records use internal PostgreSQL beneath `/var/lib/localcloud/pgdata`; operation-specific limits still apply.
Cloud Storage	`fake-gcs-server` process	Object data is stored beneath the mounted LocalCloud data root.
Pub/Sub	Google emulator process	Volatile across process restart; topics, subscriptions, and messages require recreation/reseeding.
Firestore	Google emulator process	Firestore seeding is disabled; do not infer seed or persistence guarantees from process presence.
Bigtable	`little_bigtable` artifact	LocalCloud Docker uses PostgreSQL under the mounted data root. Confirm release-unverified extended features against the exact image version you run.
BigQuery	DuckDB-backed emulator process	DuckDB files live beneath the LocalCloud data root; feature claims are release-sensitive.
Spanner	Extended emulator process	LevelDB row data plus JSON metadata beneath its data directory; mounted storage is needed across container replacement and known recovery/corruption limits apply.
Memorystore	External Valkey-compatible process on canonical port `24089`	Do not describe it as the old in-process PostgreSQL-backed RESP handler.
Cloud SQL	PostgreSQL and MySQL data planes on `24090` and `24091` plus gateway administration	Starts by default; backups, replicas, PSC, and production HA behavior remain limited.

A retained volume improves restart/container-replacement behavior only for stores that actually persist. It does not provide production replication, backups, disaster recovery, transaction parity, or durability guarantees.

Canonical container ports

The host CLI may dynamically remap these ports; generated endpoint output is authoritative for a running LocalCloud runtime.

Port	Purpose
`24080`	Gateway, console, operator APIs, and facades
`24081`	Cloud Storage
`24082`	Pub/Sub
`24083`	Firestore
`24084`	Bigtable
`24085`	Spanner gRPC
`24086`	Spanner REST/grpc-gateway — not PostgreSQL wire
`24087`	BigQuery REST
`24088`	BigQuery Storage API profile
`24089`	Memorystore/Valkey
`24090`	Cloud SQL PostgreSQL
`24091`	Cloud SQL MySQL
`24092`	GKE/k3d infrastructure
`24093`	Transparent DNS/UDP listener
`24443`	Optional native gateway HTTPS (configurable with `tls.port`)

Transparent networking and Docker socket

Both features are disabled by default in the host CLI.

Transparent networking maps host 53/udp to container 24093/udp, host 80 to gateway 24080, and host 443 to the configured native TLS port (default 24443). It requires scoped host DNS changes and certificate trust and is used only for clients that ignore custom endpoint variables.
Docker-socket access grants the container control over the host Docker daemon. It is required only for runtime workflows that deliberately create subordinate containers/clusters. Do not mount it in the beginner path.

Outbound behavior

LocalCloud is not categorically offline or zero-egress. Depending on configuration and feature use, the runtime can send telemetry, probe certificate storage, check image updates, validate licenses, validate live IAM bearer tokens, or dispatch scheduled/HTTP work. Core local workflows can continue offline after required images are present, but review Privacy and disable or isolate outbound features according to your environment.

Production boundary

Local emulation does not reproduce Google Cloud IAM enforcement, quotas, managed networking, regional behavior, concurrency, performance, replication, or disaster recovery. Consult each service operation and support level, then run an explicit real-Google-Cloud validation before release.

Was this page helpful?