# Get started with LocalCloud

> Install the LocalCloud CLI, start a local runtime, and make your first Cloud Storage request.
>
> Source: https://local.cloud/docs/

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

| Task | Read next |
| --- | --- |
| Choose a service and inspect its local behavior | [Service catalog](https://local.cloud/services/) and [compatibility](https://local.cloud/compatibility/) |
| Point application client libraries at localhost | [SDK examples](https://local.cloud/docs/sdk-examples/) |
| Connect a coding agent to local tools | [MCP setup](https://local.cloud/docs/mcp/) |
| Select services, projects, ports, and persistence | [Configuration](https://local.cloud/docs/configuration/) |
| Provision test resources declaratively | [Terraform](https://local.cloud/docs/terraform/) |
| Run integration tests in CI | [GitHub Actions](https://local.cloud/docs/github-actions/) |
| Prepare repeatable test fixtures | [Seed data](https://local.cloud/docs/seed-data/) |
| Diagnose a failed local integration | [FAQ](https://local.cloud/docs/faq/) and [runtime diagnostics](https://local.cloud/docs/#verify-and-manage-the-runtime) |

For raw Markdown, begin with the [agent instructions](https://local.cloud/ai/agents.md), [connection reference](https://local.cloud/ai/services.md), or [documentation index](https://local.cloud/llms.txt). The tutorial below is the first-time setup path.

For pull-request tests, [staging validation](https://local.cloud/docs/github-actions/#validate-a-staging-build), and AI-agent jobs, use the [GitHub Actions guide](https://local.cloud/docs/github-actions/). It covers the setup action, Docker workflows, and project integrations such as Feast. The [integration directory](https://local.cloud/docs/#integrations) 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](https://local.cloud/docs/#manual-docker-path); CLI releases after 0.1.11 have no Intel Mac build.

## Install the CLI

Install script:

### Install script

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

Homebrew:

### Homebrew

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

> **Check your CLI version**
>
> Run `localcloud --version` to see which release you have installed; the [changelog](https://local.cloud/changelog/) lists every release.

## Start your first runtime

### Check Docker

```bash
localcloud doctor
```

A usable Docker installation exits successfully and reports `status: ok`. `doctor` diagnoses Docker; it does not install or start Docker Desktop, Colima, or Docker Engine. Add `--verbose` when you need the complete JSON payload.

### Start LocalCloud

```bash
localcloud start --local-only
```

A successful command reports `started`, `already_running`, `restarted`, or `reconfigured`.

The runtime starts with the [built-in defaults](https://local.cloud/docs/configuration/#built-in-defaults).

[Runtime selection](https://local.cloud/docs/configuration/#runtime-selection) explains which data volume, and so which runtime, a command uses.

The example selects `--local-only`, which binds published ports to `127.0.0.1`. Without that flag, the current CLI publishes ports on all host interfaces. Use it again on subsequent `start`, `restart`, and `reset` commands to retain loopback binding. If a default port is already in use, the CLI can remap host ports. Use `--verbose` to inspect the complete runtime payload, including immutable container ID, ownership, image identity, mount details, and `sdk_env`.

### Configure this shell

```bash
eval "$(localcloud env)"
```

`localcloud env` discovers the compatible running container using the selected data volume and prints local-only SDK settings with its actual mapped ports. It rejects environment values that would route supported services to real Google endpoints or non-loopback HTTP endpoints.

### Open the console

```bash
localcloud console
```

The CLI opens the console for the selected runtime, project, and caller. Trust the returned `url`; do not replace it with a hard-coded port.

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

```bash
python -m pip install google-cloud-storage
```

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

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

```bash
localcloud status --verbose
localcloud logs --tail 50
```

[Stop, reset, and uninstall](https://local.cloud/docs/configuration/#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.

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

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

| Integration | Documentation |
| --- | --- |
| GitHub Actions and staging validation | [GitHub Actions guide](https://local.cloud/docs/github-actions/) for setup-localcloud, Docker workflows, test results, and cleanup. |
| Google Cloud client libraries | [SDK examples](https://local.cloud/docs/sdk-examples/) and [service guides](https://local.cloud/services/) for endpoints, credentials, and operations. |
| Local development and persistent test environments | [Configuration](https://local.cloud/docs/configuration/) for CLI lifecycle, projects, persistence, and service selection. |
| Terraform | [Terraform guide](https://local.cloud/docs/terraform/) for provider setup and runtime readiness. |
| AI agents and MCP | [MCP guide](https://local.cloud/docs/mcp/) for stdio clients and permissions; [agent instructions](https://local.cloud/ai/agents.md) for application testing. |
| Test fixtures | [Seed data](https://local.cloud/docs/seed-data/) for repeatable supported resource setup. |

For project-specific wiring, see the [Feast integration example](https://local.cloud/docs/github-actions/#integrate-an-existing-project-feast). Other CI platforms can adapt the [Docker-only workflow](https://local.cloud/docs/github-actions/#use-the-image-without-the-action-or-cli) using their own environment export and cleanup mechanisms.

## Next steps

[Configuration Select services, projects, persistence, and optional networking behavior.](https://local.cloud/docs/configuration/)[SDK Examples Configure supported client libraries using local endpoint values.](https://local.cloud/docs/sdk-examples/)[Service Catalog Browse all 27 available service guides and their documented limitations.](https://local.cloud/services/)[Compatibility Check which operations each service supports before you rely on them.](https://local.cloud/compatibility/)[Seed Data Pre-populate supported services with deterministic test data.](https://local.cloud/docs/seed-data/)[Terraform Choose endpoint-only or transparent-network Terraform setup.](https://local.cloud/docs/terraform/)