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 --local-only
eval "$(localcloud env)"

Built-in defaults

Without a configuration file or flags, localcloud start uses:

• project local-gcp-project
• caller local-developer
• persistent data
• Docker access mode auto: the socket is mounted only when selected services require it; set host.docker_socket: false to opt out
• transparent networking off
• gateway TLS off; enable it explicitly when needed

Create localcloud.yaml

The configuration format is versioned (version: 1) and logically structured by lifecycle scope:

version: 1

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

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

tls:
  enabled: false
  port: 5381

services:
  enabled: default

server:
  gateway:
    port: 5380
  logging:
    verbosity: info
  persistence: true
  auto_seed: true

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

localcloud start ./config/personal-localcloud.yaml --local-only

Configuration file selection uses this order:

1. Explicit positional path, such as localcloud start ./config/personal-localcloud.yaml --local-only.
2. LOCALCLOUD_CONFIG.
3. ./localcloud.yaml.
4. The runtime’s remembered configuration path.
5. ~/.local/share/localcloud/localcloud.yaml, or $LOCALCLOUD_HOME/localcloud.yaml when LOCALCLOUD_HOME is set.
6. Built-in defaults.

The file is a recursive overlay: omitted values inherit defaults and mapping members set to null are deleted. Command-line flags override their corresponding fields. An explicit, environment, or remembered path that is missing fails rather than silently falling back.

The current unflagged CLI publishes ports on all host interfaces. Use --local-only on start, restart, and reset to select loopback binding. host.docker_socket: auto mounts the host socket when enabled services declare a Docker dependency; false is a hard opt-out.

Runtime selection

A runtime is identified by its Docker data volume. Runtime commands select one in this order:

1. --data-volume NAME, accepted by any runtime command, which selects an isolated durable runtime identity and its storage.
2. The selected configuration’s host.data_volume.
3. The active-runtime record, revalidated before use.
4. The built-in localcloud-data fallback.

---

Select services

Use the default service selection:

services:
  enabled: default

Or declare an explicit list of services to run:

services:
  enabled:
    - gcs
    - bigquery
    - spanner
    - pubsub

The registry contains 27 API surfaces, including the auxiliary Google Sheets fixture integration. 22 are selected by default. Registry availability and default selection do not establish operation support or readiness. The currently unsupported entries are Compute Engine, Vertex AI. Check each service’s operation boundaries before use.

The default-disabled entries are Firestore, GKE, Compute Engine, Cloud Run, Vertex AI. Review the operation matrix before enabling them.

---

Service-owned runtime configuration

LocalCloud delegates service tuning to service-owned runtime config blocks under services.catalog.<id>.config. You can customize resource budgets, logging levels, and engine behavior without rebuilding container images:

version: 1

services:
  catalog:
    bigquery:
      config:
        memory_limit: 1GB
        threads: 4
        log_level: info
    memorystore:
      config:
        max_memory: 1gb
        max_memory_policy: volatile-lru
    cloudsql:
      config:
        mysql_max_connections: 100
        mysql_innodb_buffer_pool_size: 128M
    cloudiam:
      config:
        mode: open
        log_warnings: true
    spanner:
      config:
        backup_enabled: true
        backup_interval_seconds: 60

Supported service settings

---

Environment variable overrides

Documented runtime environment overrides can take precedence over corresponding runtime fields. Do not infer an override from a naming pattern; use the service configuration reference. LOCALCLOUD_CONFIG, CLI context flags, and runtime overrides have different owners.

You can also specify environment variables inside localcloud.yaml under host.environment:

host:
  environment:
    LOCALCLOUD_TELEMETRY: "false"
    LOCALCLOUD_BIGQUERY_MEMORY_LIMIT: "2GB"

---

TLS and transparent networking

LocalCloud provides native TLS termination on port 5381 (or custom configured port):

version: 1

tls:
  enabled: true
  port: 5381

host:
  transparent_network: false

• Loopback Ports (Default): Services listen on published canonical ports 5380–5405. Client SDKs use generated values, including the URL scheme where required (e.g. STORAGE_EMULATOR_HOST=http://localhost:5382). Some clients need explicit endpoint options.
• Transparent Networking: Uses local DNS on UDP port 5410 (mapped to host 53/udp), routing standard Google Cloud domains (storage.googleapis.com, bigquery.googleapis.com) directly to LocalCloud.

---

Stop, reset, and uninstall

What each lifecycle action keeps and removes:

• localcloud stop stops the runtime that runtime selection picks and retains persistent storage.
• localcloud reset --all-projects prints manual recreation steps and deletes nothing.
• The CLI may operate a compatible container created by another tool, but never removes or relabels Docker resources it does not own.
• Running the installer with --uninstall removes only a script-managed CLI and its PATH block; containers and persistent volumes remain intact.

---

Manual Docker execution

If running without the LocalCloud CLI, launch the container using the canonical 5380–5405 port range:

services:
  localcloud:
    image: agentcloud/localcloud:latest
    ports:
      - "127.0.0.1:5380-5405:5380-5405"
    environment:
      LOCALCLOUD_PROJECT: local-gcp-project
      LOCALCLOUD_PERSISTENCE: "true"
    volumes:
      - localcloud-data:/var/lib/localcloud
    deploy:
      resources:
        limits:
          memory: 4g

volumes:
  localcloud-data:

Sample data ownership

Container startup owns automatic samples. Set server.auto_seed: false to disable bootstrap samples. The retired host.seed setting is accepted but ignored, and managed CLI lifecycle commands do not mount or apply seed.yaml. Use the seed endpoints for explicit fixtures and the Console Re-seed Data action for sample replacement.