LocalCloud Pub/Sub Emulator
Get started
local.cloud — Pub/Sub Emulator .md Open tab
LocalCloud Google Cloud in-a-box

Pub/Sub emulator

Pub/Sub is asynchronous messaging between publishers and subscribers. Topics decouple event producers from the applications that process those events.

When to use Pub/Sub

Typical uses

Use when several consumers need to react to the same event independently of its publisher. Consumers acknowledge completed work and handle retries without blocking the producer.

Examples

  • Event-driven application pipelines
  • Background processing and fan-out
Messaging & Workflow

Explore another service

View all
Hello world

Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1. Install and start · shell
curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and PUBSUB_EMULATOR_HOST
eval "$(localcloud env)"
Python

Publish and acknowledge a message

2. Install SDK · shell
python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-pubsub
3. Save as hello.py
import os
from uuid import uuid4
from google.cloud import pubsub_v1

assert os.environ['PUBSUB_EMULATOR_HOST']
project = os.environ['GOOGLE_CLOUD_PROJECT']
publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
name = 'hello-' + uuid4().hex[:12]
topic = publisher.topic_path(project, name)
subscription = subscriber.subscription_path(project, name)

publisher.create_topic(request={'name': topic}, timeout=30)
try:
    subscriber.create_subscription(request={'name': subscription, 'topic': topic}, timeout=30)
    try:
        publisher.publish(topic, b'Hello, Pub/Sub!').result(timeout=30)
        response = subscriber.pull(request={'subscription': subscription, 'max_messages': 1}, timeout=30)
        assert response.received_messages
        for received in response.received_messages:
            print(received.message.data.decode())
            subscriber.acknowledge(request={'subscription': subscription, 'ack_ids': [received.ack_id]}, timeout=30)
    finally:
        subscriber.delete_subscription(request={'subscription': subscription}, timeout=30)
finally:
    publisher.delete_topic(request={'topic': topic}, timeout=30)
    subscriber.close()
    publisher.transport.close()
4. Runpython hello.py
Full example guide

Documented workflows

  • Topics, subscriptions, push/pull, StreamingPull, and acknowledgements
  • Attribute filters, dead-letter forwarding, and retries
  • Retention, snapshots, and timestamp/snapshot seek
  • Avro/Protobuf schemas, revisions, and JSON/binary validation
  • Authenticated push with locally signed OIDC tokens

Service boundaries

  • No exactly-once delivery, exports, transforms, or push payload wrappers
  • Push receivers must trust LocalCloud's issuer and JWKS; validate delivery with your application
  • Approximate local retry and retention schedules
  • Stored IAM bindings do not enforce publish or topic deletion
Try it in your project

Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

Integration

Build an integration test loop

Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Open guide
Google Cloud

Official SDK code samples

Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Browse official samples
Agent testing

Use Pub/Sub with an AI agent

Before the agent changes application logic, have it create local Pub/Sub state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

Pub/Sub local test

Use LocalCloud to test Pub/Sub locally. Read https://local.cloud/ai/agents.md, set PUBSUB_EMULATOR_HOST=localhost:5383, create a topic and subscription, publish one test message, pull or stream it, ack it, and verify the payload without using real GCP credentials.

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

Agent resources has more prompts and the AGENTS.md template.

Pub/Sub emulator FAQ

How do I run Pub/Sub locally?

Install the LocalCloud CLI, start the runtime, and export its environment, as in the example above.

Which environment variable points the SDK at the local Pub/Sub?

LocalCloud exports PUBSUB_EMULATOR_HOST=localhost:5383. Use the generated value, because the CLI picks another port when the default is in use. Some SDKs also need explicit client endpoint options; the variable alone does not route them locally.

Does the local Pub/Sub behave exactly like Google Cloud?

No. LocalCloud runs the documented workflows on this page within the service boundaries listed here. Validate behavior against real Pub/Sub before production deployment.

Related guides

Desktop view