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

Storage

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 STORAGE_EMULATOR_HOST
eval "$(localcloud env)"

Python

Upload and download an object

2. Install SDK · shell

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

3. 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())

4. Runpython hello.py

Full example guide

Node.js

Upload and download an object

2. Install SDK · shell

npm install @google-cloud/storage

3. 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;
});

4. Runnode hello.cjs

Full example guide

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

No bucket versioning, archive events, or managed folders
No lifecycle scheduling or retention enforcement
Notifications need precreated Pub/Sub topics
No event ordering or atomic object/event delivery guarantees

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