Get started with LocalCloud

Choose an integration task

Already have LocalCloud running? Go directly to the guide for your task. Export the selected runtime’s environment in the process that launches your application before making a client call.

For raw Markdown, begin with the agent instructions, connection reference, or documentation index. The tutorial below is the first-time setup path.

For pull-request tests, staging validation, and AI-agent jobs, use the GitHub Actions guide. It covers the setup action, Docker workflows, and project integrations such as Feast. The integration directory also links SDK, Terraform, and MCP setup.

This tutorial installs the LocalCloud CLI, starts a persistent local runtime, configures this shell, and verifies a Cloud Storage request. LocalCloud runs local versions of Google Cloud services for development and testing. Before you deploy to production, run final validation against real Google Cloud.

Prerequisites

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

The CLI is a standalone executable and does not require Python. Windows users and Intel Macs should use the manual Docker fallback; CLI releases after 0.1.11 have no Intel Mac build.

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 --local-only

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.

Verify and manage the runtime

localcloud status --verbose
localcloud logs --tail 50

Stop, reset, and uninstall explains what localcloud stop, localcloud reset and the installer’s --uninstall keep and remove.

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:5380-5405:5380-5405 \
  -m 4g \
  -v localcloud-data:/var/lib/localcloud \
  agentcloud/localcloud:latest

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

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

The default command does not mount /var/run/docker.sock and does not expose ports on every host interface. Docker-backed service execution and custom companion images can require Docker-socket access; transparent DNS/HTTPS routing is also opt-in. Configure those capabilities only after reviewing their security implications.

Integrations

For project-specific wiring, see the Feast integration example. Other CI platforms can adapt the Docker-only workflow using their own environment export and cleanup mechanisms.

Next steps