# LocalCloud agent guide

LocalCloud is a local Google Cloud emulator: one Docker container that answers Google Cloud SDK calls on localhost, so code and tests run without a GCP account, credentials, or billing. Validate against real Google Cloud before production.

To give a repository the same instructions, copy https://local.cloud/ai/agent-template.md into it as `AGENTS.md`.

## Start LocalCloud
```bash
curl -fsSL https://local.cloud/install.sh | sh
localcloud doctor
localcloud start --local-only
curl -fsS http://localhost:5380/readiness
eval "$(localcloud env)"
localcloud console
```

- Homebrew alternative to the first line: `brew install LocalGCloud/tap/localcloud`.
- Skip the install line when `localcloud --version` already works. If the installer prints a `source` command, run it before the next line.
- `localcloud start` waits for the runtime. The readiness check uses the default gateway port 5380; if the CLI remapped it, use the gateway URL from `localcloud status`.
- `localcloud console` opens the web console in a browser; skip it in headless sessions.

### Docker-only hosts
Without the CLI (for example on Windows), run the image directly, wait for readiness, and export the environment from the runtime:

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

for attempt in $(seq 1 60); do curl -fsS http://localhost:5380/readiness && break; sleep 2; done
eval "$(curl -fsS 'http://localhost:5380/env?format=shell')"
```

## Rules
- Use only local endpoint values. If a step would need real Google Cloud or real credentials, stop and report it.
- Never ask for or use service-account keys, application default credentials, production project IDs, or billing accounts.
- Export the LocalCloud environment in the same shell or test runner before any SDK, CLI, or Terraform step.
- If Docker or LocalCloud is unavailable, stop and report the blocker instead of falling back to real Google Cloud.
- Prefer the LocalCloud CLI. The `latest` image tag is mutable, so pin an image digest when repeatability matters.
- Back service-specific claims with the service page or https://local.cloud/compatibility/.
- Use LocalCloud only for the non-production work the Public Preview License permits.
- Before production, unset the emulator variables and validate the change against real Google Cloud.

## Workflow
1. Find the Google Cloud services, SDKs, Terraform providers, and CLI commands the project uses.
2. Start LocalCloud, or reuse the running runtime (`localcloud status`).
3. Export the environment: `eval "$(localcloud env)"` for shells and SDKs, `localcloud env --format terraform` for Terraform.
4. Run the narrowest check that proves the service path works through localhost.
5. If a feature is unsupported locally, record the gap and link the service page.

## Services
25 services run locally. Firestore, GKE, and Cloud Run are opt-in: `--services` sets the exact list of service IDs to run, so include every service the project needs, for example `localcloud start --local-only --services firestore,bigtable,spanner`. Compute Engine and Vertex AI are unsupported locally; use Google Cloud for them.

- Ports, environment variables, and guides: https://local.cloud/ai/services.md
- Capabilities and boundaries per service: https://local.cloud/ai/compatibility.md

## Endpoints
- **Web console**: `http://localhost:5380` — Inspect service health, local data, logs, and administrative state.
- **Health check**: `http://localhost:5380/health` — Inspect runtime health; use the readiness endpoint before application traffic.
- **Readiness check**: `http://localhost:5380/readiness` — Wait for configured services to be ready, then verify the exact SDK/API workflow.
- **Shell environment export**: `http://localhost:5380/env?format=shell` — Set emulator endpoint variables for local SDK and CLI workflows.
- **Terraform environment export**: `http://localhost:5380/env?format=terraform` — Set endpoint overrides for local Terraform validation without real Google Cloud credentials.

## Links
- Human guide and copyable prompts: https://local.cloud/ai/
- AGENTS.md template: https://local.cloud/ai/agent-template.md
- Markdown resource index: https://local.cloud/ai/resources.md
- Docs: https://local.cloud/docs/
- SDK examples: https://local.cloud/docs/sdk-examples/
- Terraform: https://local.cloud/docs/terraform/
- Seed data: https://local.cloud/docs/seed-data/
- Agent Skills package: https://github.com/LocalGCloud/LocalGCloud.github.io/tree/main/agent-skills
- llms.txt: https://local.cloud/llms.txt

## Contact
- AI agents and integrations: agent@local.cloud. Include the command, its output, and `localcloud --version`.
- Bugs and feature requests: https://github.com/LocalGCloud/localcloud-cli/issues