localgcloud/localcloud-cli

---

localcloud (aliased lc) is the official host CLI for LocalCloud. 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.

$ 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

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

macOS and Linux

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

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

Homebrew

brew install LocalGCloud/tap/localcloud

brew upgrade localcloud     # upgrade
brew uninstall localcloud   # remove

Upgrading

Update the CLI to the latest release:

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:

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.

Verify

$ 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

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

lc start

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 start --local-only to bind published ports to 127.0.0.1 instead. Pass --local-only on subsequent start, restart, and reset commands to keep that binding. Running start again on a live runtime is safe.

3. Configure your shell

eval "$(lc env)"

This exports the variables the official Google client libraries already read:

export STORAGE_EMULATOR_HOST="http://127.0.0.1:5382"
export BIGQUERY_EMULATOR_HOST="http://127.0.0.1:5388"
export SPANNER_EMULATOR_HOST="127.0.0.1:5386"
export BIGTABLE_EMULATOR_HOST="127.0.0.1:5385"
export GOOGLE_CLOUD_PROJECT="local-gcp-project"
export CLOUDSDK_CORE_PROJECT="local-gcp-project"
export CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE="http://127.0.0.1:5382/"
# …one entry per enabled service, plus gcloud endpoint overrides and a local access token

4. Call it from your code

No LocalCloud-specific client. No endpoint arguments. The environment does the work.

5. Look around, then stop

lc console   # open the web console for the selected project
lc status    # runtime health, endpoints, and ownership
lc logs      # recent runtime logs
lc restart   # recreate runtime with current local image (--pull to check registry)
lc stop      # stop the container; the data volume is untouched

Your data survives stop and restart. lc start brings it back exactly as it was.

Tip for AI coding agents: Skip manual shell setup! Head to AI agents & MCP to configure Cursor, Claude Code, or Windsurf in one command (lc mcp install).

How it works

  your code ──► google-cloud-* SDK ──► 127.0.0.1:5380-5406 ─────────┐
  terraform ──► GOOGLE_*_CUSTOM_ENDPOINT ───────────────────────────┤
  AI agent  ──► lc mcp (stdio) / :5380/mcp (HTTP) ──────────────────┤
                                                                    │
                      ┌─────────────────────────────────────────────┘
          ┌───────────▼─────────────────────────────────────────────┐
          │  Docker container  ·  agentcloud/localcloud             │
          │                                                         │
          │   :5380  gateway · console · admin API · MCP · facades  │
          │   :5382  Cloud Storage      :5386-87  Spanner           │
          │   :5383  Pub/Sub            :5388-89  BigQuery          │
          │   :5384  Firestore          :5390     Memorystore       │
          │   :5385  Bigtable           :5391     PostgreSQL        │
          └───────────────────┬─────────────────────────────────────┘
                              │
              Docker volume:  localcloud-data
              mounted at   :  /var/lib/localcloud

The CLI never becomes a proxy — it configures and supervises. Once lc start returns, your SDK talks to the container directly.

Three identities, deliberately separate

This is the one concept worth internalizing, because every flag follows from it:

Project and user are request context: switching them is instant and never touches Docker. Defaults are localcloud-data, local-gcp-project, and local-developer. The MCP bridge instead gives each git repository its own project, named after the repository, unless --project-id or the repository’s localcloud.yaml names one.

Ports

New runtimes prefer the canonical range 5380–5405 (plus DNS 5410/udp). With Cloud SQL MySQL enabled, the set also includes 5406, which LocalCloud’s MySQL companion container publishes. If that complete set is unavailable, the CLI proposes one contiguous alternative from 5508–5539, then 5821–5840, then 5322–5342, and asks before creating the container. Such a runtime publishes only the ports its enabled services use, so four can run beside the canonical one. To pick the host ports yourself, set host.port_range: 6000-6099 or pass --port-range 6000-6099. The CLI never scans the operating system’s general ephemeral range, and lc env always emits the ports actually in use.

Services

27 Google Cloud–compatible services, 22 enabled by default:

Select an explicit set at start time, or reset to the built-in default:

lc start --services gcs,pubsub,bigquery,firestore
lc start --services default

Commands

lc and localcloud are interchangeable in every example.

Run lc COMMAND --help for command-specific flags and the valid --fields paths.

Output modes

Every command speaks to a person and to a script from the same result:

lc status --verbose | jq '.container.url'
lc start  --fields mcp.direct_url,container.name
lc start  --dry-run                    # preview before mutating anything
NO_COLOR=1 lc doctor                   # symbols still carry status without color

Service selection is marked with ● (on) and ○ (off) as well as color, so it stays legible under NO_COLOR or a dumb terminal.

Exit codes

Recipes

An isolated environment per test suite. A second volume is a second, fully independent LocalCloud.

lc start  --data-volume ci-e2e --project-id pr-1421
lc status --data-volume ci-e2e
lc stop   --data-volume ci-e2e

Several projects on one runtime. Switching is a request-context change, not a restart.

lc start --project-id payments-dev
eval "$(lc env --project-id payments-dev)"

lc start --project-id analytics-dev
eval "$(lc env --project-id analytics-dev)"

Terraform and OpenTofu. --format terraform emits GOOGLE_*_CUSTOM_ENDPOINT variables that the Google provider reads — evaluate them into your shell, do not redirect them into a .tf file.

$ eval "$(lc env --format terraform)"
$ env | grep GOOGLE_ | head -4
GOOGLE_STORAGE_CUSTOM_ENDPOINT=http://127.0.0.1:5382/storage/v1/
GOOGLE_BIGQUERY_CUSTOM_ENDPOINT=http://127.0.0.1:5388/
GOOGLE_PROJECT=local-gcp-project
GOOGLE_OAUTH_ACCESS_TOKEN=localcloud-user.bG9jYWwtZGV2ZWxvcGVy…

$ terraform apply

Docker Compose services. Emit the same endpoints as Compose-ready environment entries.

lc env --format docker-compose

A JSON payload for scripts.

lc env --format json | jq '.STORAGE_EMULATOR_HOST'

Signed local identity for host processes. Application Default Credentials obtain LocalCloud-signed ID and access tokens for a service account from a 12-hour metadata relay on 127.0.0.1. The command warns, without changing anything, when GOOGLE_APPLICATION_CREDENTIALS or gcloud’s application-default credentials would take precedence, and keeps the relay out of a configured HTTP(S)_PROXY. See env --identity.

eval "$(lc env --identity --account [email protected])"
python my_app.py          # google.auth.default() now returns the runner account
eval "$(lc env --identity --stop)"

In CI. Skip the registry check for reproducibility, disable log tailing, and fail loudly.

lc start --data-volume ci-$GITHUB_RUN_ID --no-pull --tail 0 --verbose
# …run tests…
lc stop  --data-volume ci-$GITHUB_RUN_ID

Preview before you mutate. Lifecycle dry runs are strictly read-only and never pull.

lc start --dry-run          # every planned Docker and LocalCloud mutation, in order
lc restart --dry-run

Restart with local image vs pull. By default, lc restart recreates the container using the currently available local Docker image without checking the remote registry. Use --pull to check for and fetch newer remote images.

lc restart                  # fast restart with current local image (e.g. after building locally)
lc restart --pull           # check registry, pull newest image if available, then recreate

Reset one project without losing the others.

lc reset                    # clears the selected project; reseed from the Console
lc reset --all-projects     # prints manual recreate steps; deletes nothing

lc reset --all-projects deliberately mutates nothing. Recreating every project means deleting the data volume, and LocalCloud never runs docker volume rm for you — it prints the steps and exits non-zero so nothing is destroyed by accident.

AI agents & MCP

LocalCloud provides native Model Context Protocol (MCP) integration, giving AI coding agents a local cloud environment to build, test, and debug Google Cloud applications with standard SDKs and zero Google Cloud service charges for local workflows.

Follow the local setup guide for Claude, Codex, Cursor, and other clients for installation, GitHub plugins, connection checks, and a first test prompt. Local setup does not depend on official Directory approval.

Why agents work best with LocalCloud MCP

• On-demand auto-start: When your agent makes a call or initializes, the MCP bridge checks and starts LocalCloud in the background automatically (guarded by file lock against race conditions). Pass --no-start if you prefer manual runtime control.
• Shared default environment: Sessions using the default localcloud-data volume reuse its runtime. Select another data volume deliberately when you need a separate Docker environment.
• Safe local testing: Agents generate authentic emulator environment variables (eval "$(lc env)"), query local databases (BigQuery, Spanner, Cloud SQL), publish/pull Pub/Sub messages, and test Cloud Storage buckets directly against loopback.
• Project contexts: Use --project-id for different applications and tests. Projects share the selected runtime and are not a security boundary.

One-command setup: lc mcp install

Configure LocalCloud for your AI coding client in one command:

# Install for Cursor (user-level in ~/.cursor/mcp.json)
lc mcp install --client cursor

# Install for Claude Code (user scope via claude CLI)
lc mcp install --client claude-code

# Install for Claude Desktop (claude_desktop_config.json)
lc mcp install --client claude-desktop

# Register directly in Codex (CLI and local desktop sessions)
codex mcp add localcloud -- "$(command -v localcloud)" mcp

# Install for Gemini CLI (~/.gemini/settings.json)
lc mcp install --client gemini

# Install for Antigravity (~/.gemini/config/mcp_config.json)
lc mcp install --client antigravity

# Install for Windsurf (~/.codeium/windsurf/mcp_config.json)
lc mcp install --client windsurf

# Configure every supported client installed on this machine
lc mcp install --client all

Use claude-code explicitly for Claude Code; claude is a Claude Desktop alias. --client all configures only the clients it detects and fails if it finds none. Codex uses its own registration command. --client cline writes Cline’s shared settings file; see Cline to edit it by hand. Choose a direct connection or the GitHub plugin per client to avoid duplicate tools.

• Global by default: Installs into user-level configuration (--global). Use --project with a client that supports repository scope (Cursor, Claude Code, Gemini CLI, or Antigravity). Claude Desktop, Windsurf, and Cline always use user configuration. For a project installation in a GUI client, add --command-path "$(command -v localcloud)" to keep an absolute executable path.
• Desktop PATH resilience: On macOS, automatically resolves to permanent system binaries (/opt/homebrew/bin/localcloud or /usr/local/bin/localcloud), ensuring GUI applications launched from the Dock or Finder run smoothly without shell PATH issues.
• Custom overrides: Pass --command-path to supply a custom executable (e.g. lc or /opt/homebrew/bin/lc), or --bare to force the bare localcloud command.

Instructing your agent

Prompt your agent to use LocalCloud emulators:

You have access to the localcloud MCP server. Follow its use-localcloud-instead-of-gcp prompt. Run localcloud guide or use localcloud_get_env to direct all Google Cloud client libraries and Terraform to local loopback emulators.

You can also run lc guide in your terminal: it prints authoritative, copy-pasteable workflow guidance generated from the runtime’s own service catalog, so it cannot drift from what the image actually ships.

What the agent can do

The MCP bridge exposes the running runtime’s tools, resources, and prompts. Discover its catalog to check the capabilities available in your environment:

Reproducible cloud workflows

Run the three reproducible cloud workflows for complete agent prompts and Python/SDK test runs for Cloud Storage, Pub/Sub, and BigQuery:

(Watch the recorded demo or see the full MCP Architecture & Guide).

Manual client configuration

If you prefer to configure your MCP client manually:

{
  "mcpServers": {
    "localcloud": {
      "command": "/opt/homebrew/bin/localcloud",
      "args": ["mcp"]
    }
  }
}

(On macOS desktop apps, an absolute path like /opt/homebrew/bin/localcloud is recommended when launched from Dock/Finder; use bare "localcloud" when launching from a terminal shell with PATH configured).

For clients that speak HTTP directly, use http://127.0.0.1:5380/mcp together with X-LocalCloud-Project and X-LocalCloud-User headers.

Configuration

Sample data is owned by container startup and the Console Re-seed Data action. The CLI does not discover, mount, or apply seed files. Existing host.seed settings are ignored; use server.auto_seed: false to disable container bootstrap. Managed containers with an old CLI seed mount are recreated on start/restart with their existing data volume preserved.

Everything above works with zero configuration. When you want a versioned, shared setup, drop a localcloud.yaml beside your project:

version: 1
context:
  project: payments-dev
  user: local-developer
host:
  data_volume: payments-data
  memory: 8g
  data: persistent
  docker_socket: auto
services:
  enabled:
    - gcs
    - pubsub
    - bigquery
    - firestore

The file is a recursive partial overlay on the packaged defaults: omitted values inherit, and a mapping member set to null is deleted. The CLI resolves it in this order:

1. an explicit positional path — lc start ./custom.yaml
2. LOCALCLOUD_CONFIG
3. ./localcloud.yaml
4. the runtime’s remembered config
5. $HOME/.localcloud/localcloud.yaml
6. built-in defaults

An explicit, environment, or remembered path that is missing or unreadable fails rather than silently falling back. CLI flags override the corresponding host values.

host.docker_socket: auto (the default) mounts the host Docker socket only when an enabled service needs it — Compute Engine, Cloud Run, GKE, or Dataproc. Set true to always mount it, or false as a hard opt-out.

start, restart, reset, and stop send anonymous startup-error and hourly usage events. Set LOCALCLOUD_TELEMETRY=false or DO_NOT_TRACK=1 to turn them off; see Telemetry for exactly what is sent.

→ Full configuration reference

Troubleshooting

Still stuck? lc doctor --verbose and lc status --verbose produce the complete machine-readable state, and --debug prints the exact docker run the CLI would use.

Documentation

Development

LocalCloud CLI targets Python 3.11+ and uses uv.

uv sync --extra test                                      # install dependencies

uv run --extra test python -m pytest -q                   # full suite
uv run --extra test python -m pytest -q -m "not docker"   # no Docker required

uv run lc --help                                          # run from source

For live container lifecycle qualification, follow the Lifecycle test runbook.

Tests that need a live Docker engine are marked docker; deselect them with -m "not docker".

lc env --identity consumes LocalCloud’s typed identity session contract. The fixtures in tests/fixtures/identity/ are validated against the contract vendored in tests/fixtures/identity/localcloud-contract.json, which records the LocalCloud revision it came from; refresh it with python3 scripts/sync-identity-contract.py --localcloud , and set LOCALCLOUD_SOURCE= to also check it against that checkout. The end-to-end session test runs a real lc start and lc env --identity against an image (on Colima, use a --basetemp under your home directory so that Docker can bind-mount the configuration):

LOCALCLOUD_RUN_IDENTITY_E2E=1 LOCALCLOUD_IMAGE=localcloud: \
  uv run --frozen --extra test python -m pytest -m docker \
  tests/integration/test_identity_session_acceptance.py

License and support

LocalCloud is proprietary software governed by the LocalCloud Public Preview License. LocalCloud MCP is free for the documented local development workflows.

• Website — local.cloud
• Documentation — local.cloud/docs
• Support — open an issue on GitHub, or email [email protected]