# AGENTS.md — LocalCloud for Google Cloud development

This repository uses LocalCloud for local Google Cloud development and tests. localcloud is cloud for agents for developers, platform/DevOps engineers and teams running CI, plus AI coding agent users. Individuals, teams, nonprofits, and companies can build and test with 25 Google Cloud services on localhost in one Docker container, without a GCP account, credentials or billing. Free during the public preview. Validate against real Google Cloud before production.

## Facts
- 25 Google Cloud services run locally; ports, environment variables, and guides: https://local.cloud/ai/services.md
- Default project: `local-gcp-project`. No GCP account, Google credentials, service-account key, or billing project is needed.
- The proprietary Public Preview License permits individuals and organizations, including for-profit companies, to use LocalCloud free of charge for internal development, testing, CI, evaluation, and internal pilots.

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

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

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

## References
- Agent guide: https://local.cloud/ai/agents.md
- Capabilities and boundaries per service: https://local.cloud/ai/compatibility.md
- SDK examples: https://local.cloud/docs/sdk-examples/
- Terraform: https://local.cloud/docs/terraform/
- Seed data: https://local.cloud/docs/seed-data/
- Contact for agent integrations: agent@local.cloud