localcloud-cli

<div align="center">

# LocalCloud CLI

**A free local cloud environment for developers and AI coding agents.**

Build, test, and debug Google Cloud applications from your terminal or coding agent.
MCP connects your agent to local services, SDK configuration, test data, readiness, and diagnostics.

Run local service workflows without Google Cloud service charges, start with one command,
and create local projects for your experiments and test suites within your machine's capacity.

[Website](https://local.cloud/) · [MCP guide](https://local.cloud/docs/mcp/) · [Claude & Codex marketplace setup](docs/mcp-marketplace-guide.md)

[![Version](https://img.shields.io/github/v/release/LocalGCloud/localcloud-cli?color=4285F4&style=flat-square)](https://github.com/LocalGCloud/localcloud-cli/releases)
[![CLI](https://img.shields.io/badge/CLI-localcloud%20%7C%20lc-34A853?style=flat-square)](https://local.cloud)
[![Runtime](https://img.shields.io/badge/runtime-Docker-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com)
[![Protocol](https://img.shields.io/badge/protocol-MCP-FBBC04?style=flat-square)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org)
[![License](https://img.shields.io/badge/license-proprietary-EA4335?style=flat-square)](LICENSE)

[Install](#install) · [Quickstart](#quickstart) · [How it works](#how-it-works) · [Services](#services) · [Commands](#commands) · [AI agents & MCP](#ai-agents--mcp) · [Troubleshooting](#troubleshooting)

</div>

---

`localcloud` (aliased `lc`) is the official host CLI for [LocalCloud](https://local.cloud). It manages the
container runtime lifecycle, multi-project context, SDK environment variables, persistent Docker volumes,
and the Model Context Protocol bridge — so your application code keeps calling the same Google Cloud client
libraries it already uses, just pointed at loopback.

```console
$ lc doctor
╭── LocalCloud v0.1.12 ───────────────────────────────────────────────────────────────────────╮
│                            │ Top commands                                                   │
│ Checking LocalCloud setup  │  localcloud (or lc)    status | start | stop | restart         │
│                            │  eval $(lc env)        Exports env vars that redirect cloud se…│
│           ╭────╮           │────────────────────────────────────────────────────────────────│
│        ╭──╯    ╰──╮        │ Context                                                        │
│       ╭─╯        ╰─╮       │  Data Volume: localcloud-data        Project: local-gcp-project│
│      ╭╯            ╰╮      │  User: local-developer                                         │
│      ╰──────────────╯      │  Config: built-in defaults (overridable by ./localcloud.yaml)  │
│                            │                                                                │
├────────────────────────────┴────────────────────────────────────────────────────────────────┤
│ Supported Services (● 22 enabled · ○ 5 disabled)                                            │
│  ● Storage      ● Pub/Sub      ○ Firestore    ● Bigtable     ● Spanner      ● BigQuery      │
│  ● Cloud SQL    ● AlloyDB      ● Memorystore  ● Dataproc     ● Tasks        ● Scheduler     │
│  ● Functions    ○ Cloud Run    ○ Compute      ○ GKE          ● Workflows    ○ Vertex AI     │
│  ● Sheets       ● KMS          ● Secrets      ● IAM          ● Logging      ● Monitoring    │
│  ● Resource Mgr ● Service Usage ● Billing                                                   │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
 Tip: Run localcloud guide for AI agent workflows, or lc for the fast alias.

Docker  29.8.1 (/opt/homebrew/bin/docker) · Colima 0.10.1 (VZ, Rosetta on)
Image   agentcloud/localcloud:latest (ID: 6c619bcf17c5)
Ports   5380-5406 (in use by localcloud)
[OK] LocalCloud is ready to start  0.5s
```

## Why LocalCloud

- **27 services, one container.** Storage, Pub/Sub, BigQuery, Spanner, Bigtable, Firestore, IAM, KMS,
  Dataproc, Cloud Run and more come up together — not as a dozen emulators you wire up by hand.
- **Your SDK code doesn't change.** `eval "$(lc env)"` exports the emulator variables the official Google
  client libraries already look for. Same calls, same objects, loopback endpoints.
- **Isolated, durable environments.** A named Docker volume is the runtime's identity. Run a scratch
  environment for CI beside your everyday one, and keep data across restarts.
- **Built for humans *and* automation.** Every command renders a readable terminal summary, and the same
  result as complete JSON with `--verbose`. `--dry-run` previews mutations; `--debug` prints the equivalent
  `docker run`.
- **Agent-native.** A first-class MCP bridge lets AI coding agents provision, seed, inspect, and reset real
  GCP-shaped state as part of their own loop — not a UI a person has to click through.
- **Zero live-cloud footprint.** The CLI validates that every generated endpoint is loopback and refuses to
  emit a real `googleapis.com` address. There is no silent fallback to production.

### How it compares

|  | **LocalCloud** | `gcloud beta emulators` | Testcontainers | Real GCP dev project |
| :--- | :--- | :--- | :--- | :--- |
| Services | **27** | ~5 (Bigtable, Datastore/Firestore, Pub/Sub, Spanner) | Wraps the same emulators | All |
| Setup | One CLI command | One process per service | Written in test code | Project, billing, IAM |
| SDK wiring | `eval "$(lc env)"` | Per-emulator, manual | Per-container, in code | ADC + real credentials |
| Web console | Built in | — | — | Yes |
| Terraform / OpenTofu | `lc env --format terraform` | — | — | Yes |
| Agent control (MCP) | Built in | — | — | — |
| Data persistence | Docker volume, survives restarts | Process lifetime | Test lifetime | Durable |
| Cost / credentials | None | None | None | Billed, real keys |

> Breadth is service **availability** — a callable, service-level integration. Operation-level parity is
> service-specific and recorded per service in the LocalCloud compatibility matrix.

## Install

### Prerequisites

Docker Desktop, Colima, OrbStack, Rancher Desktop, or Docker Engine, installed and running. LocalCloud
needs at least **4 GiB** of memory available to the container for stable operation.

No Docker yet? On macOS with Homebrew, `lc doctor --fix` (or `lc start` in a terminal) offers to install
[Colima](https://github.com/abiosoft/colima), a free, lightweight Docker engine, and starts it with 4 CPUs
and 8 GiB of memory.

On Apple Silicon, run the Docker VM on **VZ with Rosetta** rather than QEMU: it is faster, and QEMU has
known issues with LocalCloud (the BigQuery emulator can fail under it). `lc doctor` reports the Docker
app, its VM type and Rosetta, and `lc doctor --fix` offers to switch Colima or Rancher Desktop.

LocalCloud's image also has an eStargz build, and `lc start --estargz` runs it. With the
[Stargz Snapshotter](https://github.com/containerd/stargz-snapshotter) as Docker's storage driver, Docker
pulls it lazily: a smaller download and a faster start. Without the snapshotter LocalCloud works the same
and Docker downloads the whole image. `lc doctor` reports **Lazy pulling** and the
[steps to turn it on](docs/cli-reference.md#doctor).

### macOS and Linux

```sh
curl -fsSL https://local.cloud/install.sh | sh
```

The installer adds `localcloud` and the shorter `lc` alias when available.

### Homebrew

```sh
brew install LocalGCloud/tap/localcloud

brew upgrade localcloud     # upgrade
brew uninstall localcloud   # remove
```

### Upgrading

Update the CLI to the latest release:

```sh
lc update
```

`lc update` detects how LocalCloud was installed (script installer or Homebrew) and upgrades the CLI in place. For Homebrew, `brew upgrade localcloud` also works.

### Standalone binaries

Signed release archives with Sigstore verification bundles are published for:

| Platform | Architectures | Minimum |
| :--- | :--- | :--- |
| macOS | Apple Silicon | macOS 13+ |
| Linux | `x86_64`, `aarch64` | glibc 2.35+ (Ubuntu 22.04+) |

Intel Macs are not supported: 0.1.11 was the last release with an Intel macOS archive.

Windows users can run the container directly — see the
[Docker setup instructions](https://local.cloud/docs/getting-started/).

### Verify

```console
$ lc --version
localcloud 0.1.12 (commit 6e45b85cad86, released 2026-10-13)
```

Release builds embed their exact source commit and release date, so a binary can always be traced back.

## Quickstart

Five minutes from nothing to a working Cloud Storage bucket.

### 1. Check your machine

```sh
lc doctor
```

Confirms Docker connectivity, reports the Docker app and its VM setup, and shows the resolved LocalCloud
context. Continue when the last line starts with `[OK]`. It creates no LocalCloud state, so it is always safe
to run first.
If it lists **Setup** findings, `lc doctor --fix` offers to fix them, asking before each change.

### 2. Start the runtime

```sh
lc start
```

```console
Config        built-in defaults (overridable by ./localcloud.yaml)
Data volume   localcloud-data
Origin        managed
Project       local-gcp-project
User          local-developer
Image         agentcloud/localcloud:latest
Image status  Available locally
URL           http://127.0.0.1:5380
Ports         5380-5406
Services      alloydb, bigquery, bigtable, cloudbilling, cloudfunctions, cloudiam,
              cloudresourcemanager, cloudscheduler, cloudsql, cloudtasks, dataproc, gcs,
              kms, logging, memorystore, monitoring, pubsub, secretmanager, serviceusage,
              sheets, spanner, workflows
[OK] LocalCloud is ready  8.4s
```

`start` checks the registry for a newer image by default (`--no-pull` to skip), publishes the canonical
ports on all host interfaces, waits for service readiness, and tails logs for five seconds.
Use `lc