Architecture

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

Request flow

1. localcloud start --local-only selects a Docker data volume, discovers or creates one compatible runtime that listens only on localhost, and maps published canonical ports in the 5380–5405 range.
2. localcloud env resolves that runtime and returns environment variables and endpoint values for the selected project and caller.
3. SDK, REST, gRPC, and Terraform requests reach a direct emulator port or the gateway on canonical container port 5380 (HTTP) or 5381 (HTTPS / TLS).
4. 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. localcloud reset --all-projects prints manual full-recreation steps and deletes nothing.

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

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 if conflicts arise; generated endpoint output from localcloud env is authoritative for a running runtime.

LocalCloud organizes its network ports into clean, continuous tiers:

• 5380–5405: In-container published range (5380–5394 active services and TLS, 5395–5405 reserved buffer for future service additions).
• 5406 & 5443–5465: External companion & child host processes (5406 Cloud SQL MySQL companion container, 5443–5465 GKE k3d child clusters with 5443 as primary).
• 5410–5414: Specialized & in-container loopback (5410/udp DNSmasq scoped DNS, 5411 Firestore private, 5412 BigQuery REST private, 5413 BigQuery Storage gRPC private, 5414 Supervisor XML-RPC private).

Published TCP Block (5380–5405)

Shared Gateway Facades (Port 5380 / 5381)

All service control planes and in-process facades connect through the shared gateway on 5380 (HTTP/h2c) or 5381 (HTTPS/TLS) rather than individual dedicated ports. These include:

• Security & Identity: Cloud Secret Manager, Cloud KMS, Cloud IAM
• Messaging & Integration: Cloud Tasks, Cloud Scheduler, Cloud Workflows
• Operations: Cloud Logging, Cloud Monitoring, Cloud Resource Manager, Service Usage, Cloud Billing
• Compute & Serverless: Cloud Functions (2nd Gen), Cloud Run, Dataproc (control plane), GKE (control plane), Compute Engine
• Databases: Cloud SQL (control plane), AlloyDB (control plane)
• Auxiliary Integration APIs: Google Sheets

Companions and Subordinate Workloads

Internal Loopback Listeners (Never Published to Host)

Transparent networking and Docker socket

Transparent networking is disabled by default. Docker access defaults to auto; the socket is mounted when selected services declare that dependency. Set host.docker_socket: false to opt out. Unflagged CLI lifecycle commands publish ports on all host interfaces; the example above selects loopback explicitly.

• Transparent networking maps host 53/udp to container 5410/udp, host 80 to gateway 5380, and host 443 to the configured native TLS port (5381). 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 or clusters (such as Cloud SQL MySQL or GKE k3d). In-container BigQuery runs natively via Supervisord and does not require Docker socket access.

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.