Cloud Storage emulator

Cloud Storage stores files as objects inside buckets. Use it for application uploads, datasets, and artifacts that need an object-storage API.

When to use Cloud Storage

Typical uses

Use when your application stores unstructured files and addresses each object by bucket and name, with uploads, downloads, and object metadata handled through an API.

Examples

User uploads and downloads
Data pipeline inputs and outputs

Example usage

Service ID: gcs. Starts by default. Use an already running LocalCloud runtime for the examples below.

Export the local project and mapped endpoints in your client process, then use the client settings below. First-time setup

# Export GOOGLE_CLOUD_PROJECT and STORAGE_EMULATOR_HOST
eval "$(localcloud env)"

Python

Upload and download an object

Upload and download a text object; Cloud Storage stores application files in addressable buckets.

Create a bucket and round-trip a text object locally.

SDK dependencies

Run in a new example directory

python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-storage

Save as hello.py

import os
from google.api_core.exceptions import NotFound
from google.auth.credentials import AnonymousCredentials
from google.cloud import storage

assert os.environ['STORAGE_EMULATOR_HOST']
client = storage.Client(
    project=os.environ['GOOGLE_CLOUD_PROJECT'],
    credentials=AnonymousCredentials(),
)
bucket = client.bucket("localcloud-sdk-example")

try:
    bucket.reload()
except NotFound:
    bucket.create()

blob = bucket.blob("data.txt")
blob.upload_from_string("Hello from LocalCloud!")
print(blob.download_as_text())

Run the example

python hello.py

Verify the result

The command completes successfully and prints the expected output shown below.

Expected output

Hello from LocalCloud!

Full example guide

Node.js

Upload and download an object

Upload and download a text object; Cloud Storage stores application files in addressable buckets.

Use @google-cloud/storage with generated local endpoints.

SDK dependencies

Run in a new example directory

npm install @google-cloud/storage

Save as hello.cjs

const { Storage } = require('@google-cloud/storage');

if (!process.env.STORAGE_EMULATOR_HOST || !process.env.GOOGLE_CLOUD_PROJECT) {
  throw new Error('Export the LocalCloud environment before running this example.');
}
const storage = new Storage({ projectId: process.env.GOOGLE_CLOUD_PROJECT });
const bucket = storage.bucket('localcloud-sdk-example');

async function main() {
  const [exists] = await bucket.exists();
  if (!exists) await storage.createBucket(bucket.name);
  await bucket.file('data.txt').save('Hello from LocalCloud!');
  const [content] = await bucket.file('data.txt').download();
  console.log(content.toString());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Run the example

node hello.cjs

Verify the result

The command completes successfully and prints the expected output shown below.

Expected output

Hello from LocalCloud!

Full example guide

Java

Upload and download an object

Upload and read back a text object; Cloud Storage gives application files a durable bucket-and-object interface.

Use the Storage SDK with the generated HTTP endpoint and local anonymous credentials. Requires JDK 17+ and Maven.

SDK dependencies

Run in a new example directory

cat > pom.xml <<'XML'
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId><artifactId>local-example</artifactId><version>1</version>
  <dependencies><dependency>
    <groupId>com.google.cloud</groupId><artifactId>google-cloud-storage</artifactId><version>2.75.0</version>
  </dependency></dependencies>
</project>
XML
mvn -q dependency:build-classpath -Dmdep.outputFile=classpath.txt

Save as Hello.java

import com.google.cloud.NoCredentials;
import com.google.cloud.storage.*;
import java.nio.charset.StandardCharsets;
import java.util.Objects;
import java.util.UUID;

public class Hello {
  public static void main(String[] args) {
    var endpoint = Objects.requireNonNull(System.getenv("STORAGE_EMULATOR_HOST"));
    var storage = StorageOptions.newBuilder()
        .setProjectId(Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT")))
        .setHost(endpoint).setCredentials(NoCredentials.getInstance()).build().getService();
    var bucket = storage.create(BucketInfo.of("example-" + UUID.randomUUID()));
    var object = BlobId.of(bucket.getName(), "hello.txt");
    try {
      storage.create(BlobInfo.newBuilder(object).build(),
          "Hello from LocalCloud!".getBytes(StandardCharsets.UTF_8));
      System.out.println(new String(storage.readAllBytes(object), StandardCharsets.UTF_8));
    } finally {
      storage.delete(object);
      storage.delete(bucket.getName());
    }
  }
}

Run the example

java --class-path "$(cat classpath.txt)" Hello.java

Verify the result

The command completes successfully and prints the expected output shown below.

Expected output

Hello from LocalCloud!

gcloud CLI

List local storage buckets

List available buckets; Cloud Storage groups uploads, datasets, and build artifacts into named object containers.

The Google Cloud CLI uses a separate endpoint override. These settings target the default open IAM mode.

Discovery check · reads existing local state.

Configure gcloud CLI

: "${STORAGE_EMULATOR_HOST:?Export the LocalCloud environment first}"
export CLOUDSDK_CORE_PROJECT="${GOOGLE_CLOUD_PROJECT:?Export the LocalCloud environment first}"
export CLOUDSDK_AUTH_DISABLE_CREDENTIALS=true
export CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE="${STORAGE_EMULATOR_HOST%/}/"

Run in your terminal

gcloud storage buckets list

Verify the result

The request succeeds. An empty list or no printed rows is valid before matching resources exist. Continue with the documented workflows for a resource test.

Verify a resource workflow by creating isolated state, performing the operation, and reading the result back. Run cleanup even after a failure; delete only test-owned resources.

Connection failed? Check localcloud status --verbose, enabled services, and client exports. Stop accidental Google Cloud calls; correct local routing before retrying.

Documented workflows

Bucket CRUD; object upload, download, listing, and deletion

Create a bucket, upload a fixture, and assert its downloaded bytes. List and delete owned objects to test cleanup.
Bucket IAM and mode-aware object authorization

Set a bucket policy, then test allowed and denied object requests in the chosen IAM mode through direct listeners and the gateway.
Object event delivery to local Pub/Sub topics

Create a Pub/Sub topic and bucket notification. Upload, update metadata, or delete an object, then assert the event type and object name.
HMAC keys and signed XML requests

Create a service-account HMAC key and sign XML requests. Rotate or revoke it, then assert that the old signature is rejected.

Service boundaries

Versioning and archive events await image validation; managed folders are unavailable
Lifecycle, retention, holds, and encryption metadata are stored without enforcement
Notifications require existing topics; ordering and atomic object/event delivery are not guaranteed

Code examples and integrations

Integration

Build an integration test loop

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

Open guide

Comparison

Cloud Storage emulator feature comparison

Browse features by category, see which ones only LocalCloud offers, and open Google's documentation for each.

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 Cloud Storage with an AI agent

Before the agent changes application logic, have it create local Cloud Storage 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.

Cloud Storage local test

Use LocalCloud to test Cloud Storage locally. Read https://local.cloud/ai/agents.md, set STORAGE_EMULATOR_HOST=http://localhost:5382, create a bucket, upload a small object, list it, download it, and verify content 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.

Cloud Storage emulator FAQ

How do I run Cloud Storage locally?

Start LocalCloud using the setup guide, then export its environment in the same terminal as your application.

Which environment variable points the SDK at the local Cloud Storage?

LocalCloud exports STORAGE_EMULATOR_HOST=http://localhost:5382. 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 Cloud Storage behave exactly like Google Cloud?

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

Related guides

Compatibility: compare all 27 service guides.
Configuration: service selection and runtime settings.
Official Cloud Storage documentation : service concepts and cloud usage.

Cloud Storage emulator

Typical uses

Explore another service

Example usage

Python

Upload and download an object

Save as hello.py

Run the example

Verify the result

Expected output

Node.js

Upload and download an object

Save as hello.cjs

Run the example

Verify the result

Expected output

Java

Upload and download an object

Save as Hello.java

Run the example

Verify the result

Expected output

gcloud CLI

List local storage buckets

Configure gcloud CLI

Run in your terminal

Verify the result

Documented workflows

Bucket CRUD; object upload, download, listing, and deletion

Bucket IAM and mode-aware object authorization

Object event delivery to local Pub/Sub topics

HMAC keys and signed XML requests

Service boundaries

Code examples and integrations

Build an integration test loop

Cloud Storage emulator feature comparison

Official SDK code samples

Use Cloud Storage with an AI agent

Cloud Storage local test

Cloud Storage emulator FAQ

How do I run Cloud Storage locally?

Which environment variable points the SDK at the local Cloud Storage?

Does the local Cloud Storage behave exactly like Google Cloud?

Related guides