Getting Started

The Shelby S3 Gateway provides an Amazon S3-compatible API for accessing Shelby blob storage. It allows you to use familiar S3 tools and libraries (AWS SDK, rclone, Cyberduck, DuckDB, etc.) to interact with blobs stored on Shelby without writing custom code.

Key Concepts

S3 Concept	Shelby Equivalent	Notes
Bucket	Shelby account address	Your Aptos address (e.g., `0x0694a79...`). If you've set up the Shelby CLI, run `shelby account info` to find it
Object	Shelby blob/file	Accessed by key (path) within a bucket
`accessKeyId`	Shared signing identity	Not an AWS credential. Identifies which credential signed the request. The gateway rejects requests with an unrecognized `accessKeyId`. Must match between your gateway config and S3 client (i.e., rclone, boto3, AWS CLI)
`secretAccessKey`	Shared signing secret	Not an AWS credential. Your S3 client (i.e., rclone, boto3, AWS CLI) uses this to sign each request; the gateway uses it to verify the signature. Never sent over the network. Must match between your gateway config and S3 client
`aptosPrivateKey`	Aptos Ed25519 private key	Your Aptos private key. If you've configured the Shelby CLI, you can copy your `private_key` from `~/.shelby/config.yaml`
Region	`shelbyland`	Default S3 region for SigV4 signing. Must match between gateway config and S3 client
Authentication	AWS SigV4 signing	Standard S3 signature protocol — works with any S3-compatible client

Prerequisites

A Shelby account — if you haven't created one yet, install the Shelby CLI and run shelby account create
rclone (optional, for the verification step)

Quick Start

Find your account address

If you've set up the Shelby CLI, run:

shelby account info

Note the address field (e.g., 0x0694a79...). This is your Shelby account address and will be used as your S3 bucket name.

Create a config file

Create a shelby.config.yaml file in your working directory:

shelby.config.yaml

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
    aptosPrivateKey: <YOUR_APTOS_PRIVATE_KEY>

buckets:
  - <YOUR_SHELBY_ACCOUNT_ADDRESS>

Placeholder	Where to find it
`<YOUR_API_KEY>`	Your Shelby API key
`<YOUR_APTOS_PRIVATE_KEY>`	If you've set up the Shelby CLI, copy your `private_key` from `~/.shelby/config.yaml`
`<YOUR_SHELBY_ACCOUNT_ADDRESS>`	If you've set up the Shelby CLI, the `address` from `shelby account info`

See Configuration for the full reference of all options.

Start the gateway

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

Output

Loaded config from: shelby.config.yaml
S3 Gateway is running on http://localhost:9000
API Reference: http://localhost:9000/spec

Connect an S3 client

The gateway authenticates requests using S3-standard SigV4 signing. Your S3 client needs an access key ID and secret access key to sign requests — these are shared secrets between the client and the gateway, not AWS credentials.

When no credentials are specified in the gateway config, it uses these defaults:

Field	Default value
`accessKeyId`	`AKIAIOSFODNN7EXAMPLE`
`secretAccessKey`	`wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`
`region`	`shelbyland`

Configure your S3 client with these same values. For example, with rclone:

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

See Integrations for setup with other tools (boto3, AWS CLI, DuckDB, Cyberduck, etc.).

Verify it's working

# List buckets
rclone lsd shelby:

# List files in a bucket (use your account address)
rclone ls shelby:<YOUR_SHELBY_ACCOUNT_ADDRESS>

CLI Options

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

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

Next Steps

Configuration — All configuration options including custom credentials
Downloads — Download files, list objects, query with DuckDB
Uploads — Upload files (requires Aptos signer)
Integrations — Tool-specific setup (rclone, boto3, AWS SDK, etc.)

Getting Started

On this page