Configuration

The LocalCloud CLI reads localcloud.yaml, starts the Docker runtime, and returns the endpoints assigned to that runtime. Start with the defaults, then add only the settings you need.

localcloud start
eval "$(localcloud env)"

Create localcloud.yaml

The current configuration format is versioned and grouped by purpose:

version: 1

context:
  project: local-gcp-project
  user: local-developer

host:
  data_volume: localcloud-data
  seed: auto
  data: persistent
  memory: 4g
  transparent_network: false
  environment: {}

services:
  enabled: default

server:
  logging:
    verbosity: info

Run localcloud start from the directory containing the file, or pass another file explicitly:

localcloud start ./config/personal-localcloud.yaml

LocalCloud chooses a file in this order: the path passed on the command line, LOCALCLOUD_CONFIG, ./localcloud.yaml, the selected runtime’s remembered file, then built-in defaults. Command-line options such as --memory, --services, --data-volume, --project-id, and --user take precedence over file values.

Older flat keys such as project:, data_volume:, and a scalar services: are no longer accepted. Use context.project, host.data_volume, and services.enabled as shown above.

Select services

Use the built-in set:

services:
  enabled: default

Or start only the services you need:

services:
  enabled:
    - gcs
    - firestore
    - pubsub

All 27 listed services are available, but only 21 start by default. Firestore is available and disabled by default because seed loading is not complete. Pro services also depend on the license tier available to the running image.

Service ID	Service	Starts by default	Minimum tier
gcs	Cloud Storage	yes	community
pubsub	Pub/Sub	yes	community
firestore	Firestore	no	community
bigtable	Bigtable	yes	pro
spanner	Spanner	yes	pro
bigquery	BigQuery	yes	community
sheets	Google Sheets	yes	community
secretmanager	Secret Manager	yes	community
cloudtasks	Cloud Tasks	yes	community
cloudscheduler	Cloud Scheduler	yes	community
cloudfunctions	Cloud Functions (2nd Gen)	yes	community
alloydb	AlloyDB	yes	community
dataproc	Dataproc	yes	community
cloudiam	Cloud IAM	yes	community
cloudresourcemanager	Cloud Resource Manager	yes	community
serviceusage	Service Usage	yes	community
cloudbilling	Cloud Billing	yes	community
logging	Cloud Logging	yes	community
monitoring	Cloud Monitoring	yes	community
gke	GKE	no	pro
compute	Compute Engine	no	pro
cloudrun	Cloud Run	no	pro
memorystore	Memorystore (Redis/Valkey)	yes	community
workflows	Cloud Workflows	yes	community
vertexai	Vertex AI	no	pro
kms	Cloud KMS	no	pro
cloudsql	Cloud SQL	yes	community

Projects and local identity

context.project sets the runtime’s default project. context.user sets the local caller used by the CLI. You can override either for a command:

localcloud start --project-id personal-demo --user alice
eval "$(localcloud env --project-id personal-demo --user alice)"

The Docker volume is the durable runtime identity. Use a different volume when you want isolated local data:

host:
  data_volume: localcloud-experiment

The CLI does not remove or relabel Docker resources it does not own.

Runtime settings

Settings under server are merged with the runtime defaults. For example:

version: 1
server:
  persistence: true
  auto_seed: true
  iam:
    mode: permissive
  logging:
    verbosity: debug

Common environment overrides remain available:

Place CLI-managed environment overrides under host.environment:

host:
  environment:
    LOCALCLOUD_TELEMETRY: "false"

TLS and transparent networking

The CLI enables gateway TLS unless you pass --no-tls. Transparent networking is separate and remains off by default.

version: 1
host:
  transparent_network: true
tls:
  enabled: true
  port: 24443

Transparent mode uses host port 53/udp for scoped DNS, host port 80 for gateway HTTP, and host port 443 for gateway HTTPS. It requires privileged host changes and certificate trust. Follow the Terraform guide when a client cannot use generated custom endpoints.

Connect applications

Always use values generated by the running CLI because occupied host ports may be remapped:

eval "$(localcloud env)"
localcloud env --format json
localcloud env --format terraform
localcloud env --format docker-compose

Stop if an application tries to contact real Google Cloud instead of adding production credentials to a local workflow.

Manual Docker Compose

On a host where the CLI is unavailable, this loopback-only setup uses the runtime’s canonical service ports:

services:
  localcloud:
    image: jaysen2apache/localcloud:latest
    ports:
      - "127.0.0.1:24080-24092:24080-24092"
    environment:
      LOCALCLOUD_PROJECT: local-gcp-project
    volumes:
      - localcloud-data:/var/lib/localcloud
    deploy:
      resources:
        limits:
          memory: 4g

volumes:
  localcloud-data:

The Docker socket and transparent host routing are not part of the beginner setup. Keep the runtime bound to loopback and review the governing license before use.