Get started with LocalCloud

This tutorial installs the LocalCloud CLI, starts a persistent local runtime, configures this shell, and verifies a Cloud Storage request. LocalCloud emulates bounded development workflows; always run final validation against real Google Cloud before production deployment.

Prerequisites

• Docker Desktop, Colima, or Docker Engine is installed and running.
• A supported native CLI host: macOS 13+ or Linux with glibc 2.35+, on ARM64 or AMD64.
• curl, tar, sed, sort, and either sha256sum or shasum.

The standalone CLI is a frozen executable and does not require Python. Windows users should use the manual Docker fallback.

Install the CLI

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

brew install LocalGCloud/tap/localcloud

The install script downloads the appropriate macOS or Linux release, verifies its SHA-256 checksum, validates the exact archive members, and runs the executable to confirm its semantic version. Release automation separately publishes Sigstore bundles, but install.sh does not verify those bundles.

In an interactive terminal, the installer can offer to run diagnostics and start LocalCloud after you confirm. In automation or with --no-start, it prints absolute-path next steps instead. If it adds the CLI to your shell startup file, run the exact source command printed by the installer before continuing.

Start your first runtime

localcloud doctor

localcloud start

eval "$(localcloud env)"

localcloud console

Make your first API call

Install the Python Cloud Storage client if needed, then run this repeatable example in the same shell where you evaluated localcloud env:

python -m pip install google-cloud-storage

from google.api_core.exceptions import NotFound
from google.cloud import storage

client = storage.Client(project="local-gcp-project")
bucket = client.bucket("localcloud-quickstart")

try:
    bucket.reload()
except NotFound:
    bucket.create()

blob = bucket.blob("hello.txt")
blob.upload_from_string("Hello, LocalCloud!")
print(blob.download_as_text())

The example safely reuses the same local bucket and overwrites the same object, so it can run repeatedly with the default persistent volume. The expected output is:

Hello, LocalCloud!

If the SDK tries to contact Google Cloud, stop instead of adding real credentials. Re-run eval "$(localcloud env)" in the shell or process that launches the application. The example is idempotent: it reuses the bucket and overwrites the same object when run again.

Verify and manage the runtime

localcloud status --verbose
localcloud logs --tail 50

Use --data-volume NAME with any runtime command to select an isolated durable runtime identity and its storage. Without the flag or a configured data_volume, runtime commands use the revalidated active-runtime record before falling back to localcloud-data. localcloud stop stops that selected runtime and retains persistent storage. 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 path

Use this fallback on unsupported CLI hosts or when you deliberately do not want the host CLI. The latest tag is mutable, so prefer the CLI for normal use and pin an image digest when repeatability matters.

docker volume create localcloud-data

docker run -d --name localcloud \
  -p 127.0.0.1:24080-24092:24080-24092 \
  -m 4g \
  -v localcloud-data:/var/lib/localcloud \
  jaysen2apache/localcloud:latest

Verify the runtime and configure the shell through root operator endpoints:

curl -fsS http://localhost:24080/health
eval "$(curl -fsS 'http://localhost:24080/env?format=shell')"

The default command does not mount /var/run/docker.sock and does not expose ports on every host interface. GKE, Compute Engine, Cloud Run, and Dataproc execution can require explicit Docker-socket access; transparent DNS/HTTPS routing is also opt-in. Configure those capabilities only after reviewing their security implications.

Next steps