# Configuration

> Configure LocalCloud projects, services, storage, TLS, and service-owned runtime behavior.
>
> Source: https://local.cloud/docs/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.

```bash
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:

```yaml
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:

```bash
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.

> **Schema Migration**
>
> Legacy flat top-level keys such as `project:`, `data_volume:`, and `server.iam:` are rejected. Use hierarchical keys: `context.project`, `host.data_volume`, and service-owned configurations under `services.catalog.<service>.config`.

## 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:

```yaml
services:
  enabled: default
```

Or declare an explicit list of services to run:

```yaml
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 ID | Service Name | Starts by Default | Minimum Tier |
| --- | --- | --- | --- |
| `firestore` | Firestore | no | Community |
| `bigtable` | Bigtable | yes | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) |
| `spanner` | Spanner | yes | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) |
| `alloydb` | AlloyDB | yes | Community |
| `memorystore` | Memorystore (Redis/Valkey) | yes | Community |
| `cloudsql` | Cloud SQL | yes | Community |
| `pubsub` | Pub/Sub | yes | Community |
| `cloudtasks` | Cloud Tasks | yes | Community |
| `cloudscheduler` | Cloud Scheduler | yes | Community |
| `workflows` | Cloud Workflows | yes | Community |
| `cloudfunctions` | Cloud Functions (2nd Gen) | yes | Community |
| `gke` | GKE | no | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) |
| `compute` | Compute Engine | no | — |
| `cloudrun` | Cloud Run | no | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) |
| `vertexai` | Vertex AI | no | — |
| `secretmanager` | Secret Manager | yes | Community |
| `cloudiam` | Cloud IAM | yes | Community |
| `kms` | Cloud KMS | yes | [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier) |
| `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 |
| `gcs` | Cloud Storage | yes | Community |
| `bigquery` | BigQuery | yes | Community |
| `dataproc` | Dataproc | yes | Community |
| `sheets` | Google Sheets (Auxiliary integration API) | yes | Community |

* * *

## 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:

```yaml
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

| Service | Setting Key | Default | Description |
| --- | --- | --- | --- |
| **BigQuery** | `memory_limit` | `512MB` | Maximum DuckDB columnar OLAP memory budget. |
|  | `threads` | `2` | Worker threads allocated for analytical query execution. |
|  | `log_level` | `info` | Logging verbosity for the GoogleSQL engine. |
| **Cloud IAM** | `mode` | `open` | IAM evaluation mode (`open`, `permissive`, or `strict`). |
|  | `log_warnings` | `true` | Log evaluation warnings for missing or incomplete roles. |
| **Cloud SQL** | `mysql_max_connections` | `50` | Connection pool limit for MySQL 8.4 companion. |
|  | `mysql_innodb_buffer_pool_size` | `64M` | Memory pool allocated for MySQL InnoDB caching. |
| **Memorystore** | `max_memory` | `512mb` | Redis memory capacity limit. |
|  | `max_memory_policy` | `noeviction` | Eviction strategy when memory limit is reached. |
| **Spanner** | `backup_enabled` | `false` | Enable automated background backup schedule worker. |
|  | `backup_interval_seconds` | `60` | Sweep interval for backup schedules. |

* * *

## 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.

| Variable | Default | Purpose |
| --- | --- | --- |
| `LOCALCLOUD_PROJECT` | `local-gcp-project` | Default Google Cloud project ID. |
| `LOCALCLOUD_DATA_DIR` | `/var/lib/localcloud` | Base path for persistent emulator data inside the container. |
| `LOCALCLOUD_PERSISTENCE` | `true` | Retain state across container restarts on mounted volumes. |
| `LOCALCLOUD_SERVICES` | `default` | Comma-separated list of enabled service IDs. |
| `LOCALCLOUD_IAM_MODE` | `open` | Default Cloud IAM evaluation mode (`open`, `permissive`, `strict`). |
| `LOCALCLOUD_BIGQUERY_MEMORY_LIMIT` | `512MB` | Override BigQuery DuckDB memory budget. |
| `LOCALCLOUD_TELEMETRY` | `true` | Anonymous runtime diagnostic metrics preference. |

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

```yaml
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):

```yaml
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](https://local.cloud/docs/configuration/#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:

```yaml
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](https://local.cloud/docs/seed-data/) for explicit fixtures and the Console Re-seed Data action for sample replacement.