# localcloud is cloud for agents.

LocalCloud runs Google Cloud-compatible services locally for development, integration tests, and CI. Connect your existing SDKs through local endpoints, or use the LocalCloud MCP server. No Google Cloud account or credentials are required for local workflows.

- **runtime**: one Docker container
- **services**: 25 local service APIs
- **connect**: Google Cloud SDKs / stdio MCP
- **scope**: development / tests / CI

Source: https://local.cloud/?audience=agents

## Choose your next step
- [Choose services](https://local.cloud/services/): Find service purposes, exact IDs, startup requirements, and client examples.
- [Integrate a repository](https://local.cloud/docs/): Configure SDKs, MCP, Terraform, CI, and test fixtures.
- [Connect through MCP](https://local.cloud/docs/mcp/): Use the LocalCloud CLI as a stdio MCP server in a coding client.

## Start with repository context
Inspect the repository and its existing agent instructions. Identify the Google Cloud services, client libraries, and tests it uses, then choose the matching service guides before changing application logic.

Read https://local.cloud/ai/agents.md. Merge relevant guidance from https://local.cloud/ai/agent-template.md into existing repository instructions; preserve the project's own rules.

## Prerequisites
Requires Docker running and the latest LocalCloud CLI. Install the CLI once with curl -fsSL https://local.cloud/install.sh | sh, or follow the setup guide. Skip installation when localcloud --version already works. If the installer prints a source command, run it before continuing.

Setup guide: https://local.cloud/docs/#install-the-cli

## Select the project and services

For a new example directory, save this as localcloud.yaml before starting. In an existing repository, merge the relevant settings into its configuration. This example selects BigQuery, Cloud Storage, and Pub/Sub; adapt the exact service IDs to your project.

### localcloud.yaml

```yaml
version: 1
context:
  project: local-gcp-project
services:
  enabled:
    - bigquery
    - gcs
    - pubsub
```

Expected result: The configuration includes every service your application needs. Firestore, GKE, and Cloud Run are opt-in.

## Start or reuse the local runtime

Run from the configured directory. Start waits for readiness and can reuse the matching runtime. Export its actual mapped endpoints in the same shell or test runner that launches your SDK; do not assume the default ports are available.

### setup.sh

```bash
localcloud doctor
localcloud start --local-only
eval "$(localcloud env)"
```

Expected result: Startup succeeds and the SDK environment points to the selected local runtime. Inspect localcloud status --verbose if startup or endpoint discovery fails.

## Verify a local SDK call

Python · BigQuery. Install the client in an isolated environment, save this file, then execute a constant query through the generated local endpoint. This verifies SDK routing without creating persistent resources.

### SDK dependencies

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-bigquery
```

### assert_query.py

```python
# First export endpoints: eval "$(localcloud env)"
import os
from google.auth.credentials import AnonymousCredentials
from google.cloud import bigquery

with bigquery.Client(
    project=os.environ["GOOGLE_CLOUD_PROJECT"],
    credentials=AnonymousCredentials(),
    client_options={"api_endpoint": os.environ["BIGQUERY_EMULATOR_HOST"]},
) as client:
    rows = list(client.query("SELECT 1 AS ok").result(timeout=30))
    assert rows[0].ok == 1
    print("ok=1")
```

### Run the example

```bash
python assert_query.py
```

Expected result: The assertion passes, the command prints ok=1, and no test resources need cleanup.

## Scope and references
Use LocalCloud for development, tests, and CI. If Docker or LocalCloud is unavailable, report the blocker instead of switching to real Google Cloud. Validate production endpoints, authentication, IAM, quotas, and regional behavior against Google Cloud before release.

- [Agent instructions](https://local.cloud/ai/agents.md)
- [Service connection reference](https://local.cloud/ai/services.md)
- [Capabilities and boundaries](https://local.cloud/ai/compatibility.md)
- [Documentation index](https://local.cloud/llms.txt)
- [License](https://local.cloud/license/)