Light, fluffy, and always free — GCP Local Emulator
No account. No auth token. No feature gates. Just docker compose up.

Quick Start · Features · Services · SDKs · Testcontainers · Compatibility · Docs

floci-gcp is a free, open-source local GCP emulator for development, testing, and CI.

It gives you GCP-shaped services on your machine without requiring a cloud account, auth token, or paid feature gates. Point your GCP SDK, gcloud CLI, Terraform, or test suite at http://localhost:4588 and keep your existing workflows.

floci-gcp is named after floccus, the cloud formation that looks like popcorn.

Quick Start

# docker-compose.yml
services:
  floci-gcp:
    image: floci/floci-gcp:latest
    ports:
      - "4588:4588"
    volumes:
      - ./data:/app/data
      # Enables Docker-backed services (Cloud Run, Cloud SQL, Kafka, GKE)
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      FLOCI_GCP_HOSTNAME: floci-gcp
      FLOCI_GCP_BASE_URL: http://floci-gcp:4588
      # Keep state across restarts in the mounted ./data volume
      FLOCI_GCP_STORAGE_MODE: hybrid

docker compose up -d

Export the GCP emulator environment variables:

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

All GCP services are available at http://localhost:4588. Credentials are not validated.

docker run -d --name floci-gcp \
  -p 4588:4588 \
  floci/floci-gcp:latest

Features

Why floci-gcp?

GCP's official emulators are fragmented — each service ships its own binary, runs on a different port, and requires separate setup. floci-gcp unifies them under a single port.

Architecture Overview

flowchart LR
    Client["GCP SDK / gcloud CLI"]

    subgraph FlociGCP ["floci-gcp, port 4588"]
        Router["HTTP/2 Router\nALPN negotiation"]

        subgraph GRPC ["gRPC services"]
            A["Pub/Sub\nFirestore\nSecret Manager\nCloud Logging\nCloud KMS\nCloud Tasks\nCloud Scheduler\nCloud Monitoring"]
        end

        subgraph REST ["REST services"]
            B["Cloud Storage\nIAM\nIAM Credentials\nDatastore\nCloud Run\nCloud Functions\nCloud SQL\nGKE\nBigQuery\nEventarc\nService Usage\nFirebase Auth"]
        end

        subgraph Docker ["Docker-backed"]
            C["Managed Kafka (Redpanda)\nCloud SQL (Postgres)\nCloud Run\nGKE (k3s)"]
        end

        Router --> GRPC
        Router --> REST
        Router --> Docker
        GRPC & REST --> Store[("StorageBackend\nmemory · hybrid · persistent · wal")]
    end

    DockerEngine["Docker Engine"]
    Client -->|"HTTP/2 :4588\nGCP wire protocols"| Router
    Docker -->|"Docker API"| DockerEngine

Supported Services

floci-gcp emulates GCP services across storage, messaging, identity, and managed infrastructure.

Real Docker Integration

floci-gcp uses real Docker containers when in-process emulation would reduce fidelity — stateful databases, connection-heavy protocols, and image-based runtimes. These services spawn sidecar containers via the host Docker daemon. Each is gated by a per-service mock flag: set it to true to keep the service metadata-only without Docker.

Docker-backed services require the Docker socket:

docker run -d --name floci-gcp \
  -p 4588:4588 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  floci/floci-gcp:latest

Overriding default images

Persistence and Storage Modes

floci-gcp supports flexible storage modes. Configure globally via FLOCI_GCP_STORAGE_MODE.

Use memory for fast CI runs. Use hybrid when you want state preserved across container restarts.

Multi-Project Isolation

GCP resource names follow projects/{project}/.... floci-gcp uses the project ID as the multi-tenancy boundary — resources in project-a are invisible to project-b.

The project ID is resolved in this order:

1. URL path segment projects/{project}/...
2. x-goog-request-params header (project=...)
3. FLOCI_GCP_DEFAULT_PROJECT_ID fallback (default: floci-local)

# Two projects, full isolation
export PUBSUB_EMULATOR_HOST=localhost:4588

gcloud pubsub topics create my-topic --project=project-a
gcloud pubsub topics create my-topic --project=project-b

# Each project has its own independent topic

SDK Integration

Point your existing GCP SDK at http://localhost:4588.

// Pub/Sub
ManagedChannel channel = ManagedChannelBuilder
    .forTarget("localhost:4588")
    .usePlaintext()
    .build();

TransportChannelProvider channelProvider =
    FixedTransportChannelProvider.create(GrpcTransportChannel.create(channel));
CredentialsProvider credentialsProvider = NoCredentialsProvider.create();

TopicAdminClient topicClient = TopicAdminClient.create(
    TopicAdminSettings.newBuilder()
        .setTransportChannelProvider(channelProvider)
        .setCredentialsProvider(credentialsProvider)
        .build());

topicClient.createTopic(TopicName.of("floci-local", "my-topic"));

// Cloud Storage
Storage storage = StorageOptions.newBuilder()
    .setHost("http://localhost:4588")
    .setProjectId("floci-local")
    .setCredentials(NoCredentials.getInstance())
    .build()
    .getService();

storage.create(BucketInfo.of("my-bucket"));
storage.create(BlobInfo.newBuilder("my-bucket", "hello.txt").build(),
    "hello from floci-gcp".getBytes());

// Firestore
FirestoreOptions options = FirestoreOptions.newBuilder()
    .setHost("localhost:4588")
    .setProjectId("floci-local")
    .setCredentials(NoCredentials.getInstance())
    .build();

Firestore db = options.getService();
db.collection("users").add(Map.of("name", "Alice", "age", 30)).get();

import os
os.environ["PUBSUB_EMULATOR_HOST"] = "localhost:4588"

from google.cloud import pubsub_v1

publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path("floci-local", "my-topic")
publisher.create_topic(request={"name": topic_path})
future = publisher.publish(topic_path, b"hello from floci-gcp")
future.result()

import os
os.environ["STORAGE_EMULATOR_HOST"] = "http://localhost:4588"

from google.cloud import storage

client = storage.Client(project="floci-local")
bucket = client.bucket("my-bucket")
client.create_bucket(bucket)

blob = bucket.blob("hello.txt")
blob.upload_from_string("hello from floci-gcp")
print(blob.download_as_text())

import os
os.environ["FIRESTORE_EMULATOR_HOST"] = "localhost:4588"

from google.cloud import firestore

db = firestore.Client(project="floci-local")
db.collection("users").add({"name": "Alice", "age": 30})
docs = db.collection("users").where("name", "==", "Alice").stream()
for doc in docs:
    print(doc.to_dict())

import { PubSub } from "@google-cloud/pubsub";

process.env.PUBSUB_EMULATOR_HOST = "localhost:4588";

const pubsub = new PubSub({ projectId: "floci-local" });
await pubsub.createTopic("my-topic");
const [subscription] = await pubsub.topic("my-topic").createSubscription("my-sub");

import { Storage } from "@google-cloud/storage";

const storage = new Storage({
  apiEndpoint: "http://localhost:4588",
  projectId: "floci-local",
});

await storage.createBucket("my-bucket");
await storage.bucket("my-bucket").file("hello.txt").save("hello from floci-gcp");

package main

import (
    "context"
    "fmt"
    "log"

    "cloud.google.com/go/pubsub"
    "google.golang.org/api/option"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

func main() {
    ctx := context.Background()

    conn, err := grpc.Dial("localhost:4588", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatal(err)
    }

    client, err := pubsub.NewClient(ctx, "floci-local",
        option.WithGRPCConn(conn))
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    topic, err := client.CreateTopic(ctx, "my-topic")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Created topic:", topic.ID())
}

export PUBSUB_EMULATOR_HOST=localhost:4588
gcloud config set project floci-local

# Pub/Sub
gcloud pubsub topics create my-topic
gcloud pubsub subscriptions create my-sub --topic=my-topic
gcloud pubsub topics publish my-topic --message="hello from floci-gcp"
gcloud pubsub subscriptions pull my-sub --auto-ack

# Cloud Storage
export STORAGE_EMULATOR_HOST=http://localhost:4588
gcloud storage buckets create gs://my-bucket
echo "hello" | gcloud storage cp - gs://my-bucket/hello.txt
gcloud storage ls gs://my-bucket

# Secret Manager
export SECRET_MANAGER_EMULATOR_HOST=localhost:4588
gcloud secrets create my-secret --replication-policy=automatic
echo -n "my-value" | gcloud secrets versions add my-secret --data-file=-
gcloud secrets versions access latest --secret=my-secret

Testcontainers

Use GenericContainer to start an isolated floci-gcp instance directly from your tests. This avoids shared state, manual daemon setup, and port conflicts.

The emulator also ships helper endpoints for test harnesses: GET /health (readiness, also at /_floci-gcp/health), GET /_floci-gcp/info (build and service info), and POST /_floci-gcp/state/reset (wipe all emulator state between tests without a restart).

@Testcontainers
class PubSubIntegrationTest {

    @Container
    static GenericContainer<?> flociGcp = new GenericContainer<>("floci/floci-gcp:latest")
        .withExposedPorts(4588)
        .waitingFor(Wait.forHttp("/health").forPort(4588));

    static TopicAdminClient topicClient;

    @BeforeAll
    static void setup() throws Exception {
        String host = flociGcp.getHost();
        int port = flociGcp.getMappedPort(4588);

        ManagedChannel channel = ManagedChannelBuilder
            .forAddress(host, port)
            .usePlaintext()
            .build();

        topicClient = TopicAdminClient.create(
            TopicAdminSettings.newBuilder()
                .setTransportChannelProvider(
                    FixedTransportChannelProvider.create(GrpcTransportChannel.create(channel)))
                .setCredentialsProvider(NoCredentialsProvider.create())
                .build());
    }

    @Test
    void shouldCreateTopic() {
        topicClient.createTopic(TopicName.of("floci-local", "test-topic"));
    }
}

import pytest
from testcontainers.core.container import DockerContainer
from google.cloud import pubsub_v1


@pytest.fixture(scope="session")
def floci_gcp():
    with DockerContainer("floci/floci-gcp:latest").with_exposed_ports(4588) as container:
        container.get_exposed_port(4588)  # wait for startup
        yield container


def test_pubsub(floci_gcp):
    port = floci_gcp.get_exposed_port(4588)
    host = floci_gcp.get_container_host_ip()

    import os
    os.environ["PUBSUB_EMULATOR_HOST"] = f"{host}:{port}"

    publisher = pubsub_v1.PublisherClient()
    topic_path = publisher.topic_path("floci-local", "test-topic")
    publisher.create_topic(request={"name": topic_path})

Compatibility Testing

The compatibility-tests directory validates floci-gcp across SDKs and IaC tools.

Run the full suite:

cd compatibility-tests && just test-java
cd compatibility-tests && just test-go
cd compatibility-tests && just test-terraform

Migrating from gcloud emulators

Google ships a separate emulator per service (gcloud beta emulators pubsub | firestore | datastore | bigtable | spanner), each its own process on its own port. floci-gcp replaces all of them with one binary on a single port (4588), reusing the same *_EMULATOR_HOST environment variables the GCP SDKs already honor — just point them at floci-gcp.

The GCP SDKs skip credential checks automatically when these variables are set, so no code changes are needed — one container replaces the fragmented per-service emulator processes.

Image Tags

Every tag combines a variant and a channel.

Use latest for stable releases, a pinned version for reproducible builds, and nightly to track main.

# Recommended
image: floci/floci-gcp:latest

# Pinned release
image: floci/floci-gcp:0.5.0

# Track main
image: floci/floci-gcp:nightly

Configuration

All settings are overridable via environment variables (FLOCI_GCP_ prefix).

Per-service enable flags (FLOCI_GCP_SERVICES_<SERVICE>_ENABLED), mock flags (*_MOCK), sidecar images, Docker networking, and DNS suffixes are documented in the full reference.

Full reference: configuration docs

Multi-container Docker Compose

When your application runs in a different container, set FLOCI_GCP_HOSTNAME to the floci-gcp service name so returned URLs resolve correctly from other containers.

services:
  floci-gcp:
    image: floci/floci-gcp:latest
    ports:
      - "4588:4588"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      FLOCI_GCP_HOSTNAME: floci-gcp
      FLOCI_GCP_BASE_URL: http://floci-gcp:4588
      # Attach spawned sidecars (Cloud Run, Cloud SQL, Kafka, GKE) to this network
      FLOCI_GCP_SERVICES_DOCKER_NETWORK: my_project_default
    networks:
      my_project_default:
        aliases:
          - localhost.floci.io
          - container.localhost.floci.io

  my-app:
    environment:
      PUBSUB_EMULATOR_HOST: floci-gcp:4588
      FIRESTORE_EMULATOR_HOST: floci-gcp:4588
      STORAGE_EMULATOR_HOST: http://floci-gcp:4588
    networks:
      - my_project_default
    depends_on:
      - floci-gcp

networks:
  my_project_default:
    name: my_project_default

The network aliases let other containers resolve virtual-hosted URLs (*.localhost.floci.io) that the emulator's embedded DNS serves for GCS and Cloud Run.

Community

Join the Floci community on Slack or GitHub Discussions. Feature ideas, compatibility questions, design tradeoffs, and rough proposals are welcome.

Star History

Contributors

License

MIT — use it however you want.