# Cloud Storage emulator

> Run Cloud Storage locally: buckets, object upload and download, IAM, Pub/Sub notifications, and HMAC-signed requests on port 5382.
>
> Source: https://local.cloud/services/cloud-storage/

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

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

Connection

Environment variable

`STORAGE_EMULATOR_HOST=http://localhost:5382`

Runtime details

- **Endpoints:** HTTP/REST :5382
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Third-Party Emulator

## 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](https://local.cloud/docs/)

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

Python:

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

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

#### Save as hello.py

```python
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

```bash
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](https://local.cloud/docs/sdk-examples/#cloud-storage-python)

Node.js:

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

```bash
npm install @google-cloud/storage
```

#### Save as hello.cjs

```javascript
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

```bash
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](https://local.cloud/docs/sdk-examples/#cloud-storage-nodejs)

Java:

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

```bash
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

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

```bash
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:

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

```bash
: "${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

```bash
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

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.
- [Cloud Storage emulator feature comparison](https://local.cloud/compare/emulators/?service=cloud-storage): Browse features by category, see which ones only LocalCloud offers, and open Google's documentation for each.
- [Official SDK code samples](https://docs.cloud.google.com/storage/docs/samples): Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

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](https://local.cloud/ai/) 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](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Storage documentation](https://docs.cloud.google.com/storage/docs/introduction): service concepts and cloud usage.