floci/floci-gcp repository overview

⁠floci-gcp

Any Cloud. Locally.
Light, fluffy, and always free: the GCP local emulator

A free, open-source local GCP emulator for development, testing, and CI. No account. No auth token. No feature gates.

Google ships a separate emulator per service, each its own process on its own port. floci-gcp replaces all of them with one binary on a single port, reusing the *_EMULATOR_HOST variables the GCP SDKs already honor.

⁠Quick Start

# docker-compose.yml
services:
  floci-gcp:
    image: floci/floci-gcp:latest
    ports:
      - "4588:4588"
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock  # Cloud Run, Cloud SQL, Kafka, GKE
    environment:
      FLOCI_GCP_HOSTNAME: floci-gcp
      FLOCI_GCP_BASE_URL: http://floci-gcp:4588
      FLOCI_GCP_STORAGE_MODE: hybrid

docker compose up -d

export PUBSUB_EMULATOR_HOST=localhost:4588
export FIRESTORE_EMULATOR_HOST=localhost:4588
export DATASTORE_EMULATOR_HOST=localhost:4588
export STORAGE_EMULATOR_HOST=http://localhost:4588
export SECRET_MANAGER_EMULATOR_HOST=localhost:4588
export FIREBASE_AUTH_EMULATOR_HOST=localhost:4588
export GOOGLE_CLOUD_PROJECT=floci-local

Credentials are not cryptographically validated. The exception is a Floci-issued downscoped token, whose GCS requests are evaluated against its Credential Access Boundary.

⁠Why floci-gcp?

All services share port 4588 via HTTP/2 ALPN negotiation.

⁠Services

floci-gcp speaks the real wire protocols: protobuf over gRPC for Pub/Sub, Firestore, Secret Manager, and Cloud Storage v2; binary HTTP/protobuf for Datastore; REST XML and JSON for Cloud Storage; REST JSON for management APIs.

Real Docker where fidelity matters. Each is gated by a *_MOCK flag to run metadata-only without Docker.

⁠Migrating from gcloud emulators

The SDKs skip credential checks automatically when these are set, so no code changes are needed.

⁠Configuration

Full reference: floci.io/floci-gcp/configuration⁠

Multi-project isolation: the project ID is the tenancy boundary, resolved from the projects/{project}/... path, then the x-goog-request-params header, then FLOCI_GCP_DEFAULT_PROJECT_ID.

Test harness endpoints: GET /health, GET /_floci-gcp/info, and POST /_floci-gcp/state/reset to wipe state between tests without a restart.

⁠Compatibility Testing

Validated across the Java, Node.js, Python, and Go GCP SDKs, the gcloud CLI, and both Terraform and OpenTofu with the Google provider. See compatibility-tests⁠.

⁠Image Tags

Stable releases ship on the 1st and 3rd Tuesday of each month. nightly tracks main.

⁠Resources

• Docs: floci.io/floci-gcp⁠
• Source: github.com/floci-io/floci-gcp⁠
• Slack: Join the Flock⁠
• Discussions: github.com/orgs/floci-io/discussions⁠
• Sponsor: github.com/sponsors/floci-io⁠

⁠License

MIT. Use it however you want.