Shelby S3 Gateway

An S3-compatible API gateway for Shelby Protocol blob storage.

Use familiar S3 tools and libraries (AWS SDK, rclone, Cyberduck, DuckDB, etc.) to access blobs stored on Shelby.

Quick Start

1. Create a shelby.config.yaml file:

network:
  name: shelbynet
  rpcEndpoint: https://api.shelbynet.shelby.xyz/shelby
  aptosFullnode: https://api.shelbynet.shelby.xyz/v1
  aptosIndexer: https://api.shelbynet.shelby.xyz/v1/graphql
  apiKey: your-api-key

server:
  port: 9000

credentials:
  - accessKeyId: AKIAIOSFODNN7EXAMPLE
    secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

buckets:
  - "0x0694a79e492d268acf0c6c0b01f42654ac050071a343ebc4226cb6717d63e4ea"

2. Start the gateway:

npx @shelby-protocol/s3-gateway --config shelby.config.yaml

3. Connect with any S3 client:

# Using rclone
rclone config create shelby s3 \
  provider=Other \
  access_key_id=AKIAIOSFODNN7EXAMPLE \
  secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
  endpoint=http://localhost:9000 \
  force_path_style=true

rclone ls shelby:0x0694a79e492d268acf0c6c0b01f42654ac050071a343ebc4226cb6717d63e4ea

CLI Options

npx @shelby-protocol/s3-gateway --help

Options:
  -c, --config <path>  Path to config file
  -p, --port <port>    Port to listen on (overrides config)
  -h, --help           Show help message

Supported Operations

The gateway currently supports read operations:

| Operation | Description | |-----------|-------------| | ListBuckets | List all configured buckets | | HeadBucket | Check if a bucket exists | | ListObjectsV1/V2 | List objects with pagination | | GetObject | Download file contents (supports Range headers) | | HeadObject | Get object metadata |

Documentation

For full documentation, configuration options, and integration guides, visit: https://docs.shelby.xyz/tools/s3-gateway

License

Apache-2.0