Configuration

The S3 Gateway is configured using a YAML config file. For advanced use cases, JavaScript/TypeScript configs are also supported.

YAML Configuration

Create a shelby.config.yaml file and run with --config:

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

Full Example

shelby.config.yaml

# Network configuration (required)
network:
  name: shelbynet              # "shelbynet" or "local"
  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         # Optional

# Server settings
server:
  host: localhost      # Bind address (default: localhost)
  port: 9000           # Listen port (default: 9000)
  region: shelbyland   # S3 region for signing (default: shelbyland)
  verbose: false       # Enable request logging (default: false)

# S3 credentials for authentication
credentials:
  - accessKeyId: AKIAIOSFODNN7EXAMPLE
    secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
  # Add more credentials as needed
  - accessKeyId: AKIA_ANOTHER_KEY
    secretAccessKey: another_secret_key

# Shelby account addresses to expose as S3 buckets (required)
buckets:
  - "0x0694a79e492d268acf0c6c0b01f42654ac050071a343ebc4226cb6717d63e4ea"
  - "0xanother_account_address"

Minimal Example

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

buckets:
  - "0x0694a79e492d268acf0c6c0b01f42654ac050071a343ebc4226cb6717d63e4ea"

With the minimal config, the gateway uses default development credentials.

Configuration Reference

Network Options (Required)

Option	Type	Default	Description
`name`	`"shelbynet"` \| `"local"`	`"shelbynet"`	Network name
`rpcEndpoint`	`string`	Network default	Shelby RPC endpoint URL
`aptosFullnode`	`string`	-	Aptos fullnode URL
`aptosIndexer`	`string`	-	Aptos indexer URL
`apiKey`	`string`	-	API key for authentication

Server Options

Option	Type	Default	Description
`host`	`string`	`"localhost"`	Bind address for the server
`port`	`number`	`9000`	Port to listen on
`region`	`string`	`"shelbyland"`	S3 region for SigV4 signing
`verbose`	`boolean`	`false`	Enable detailed request logging

The region setting must match what your S3 clients use for signing requests. Some tools require a standard AWS region like "us-east-1".

Credentials

Array of S3 credential objects. If not specified, default dev credentials are used.

Field	Type	Description
`accessKeyId`	`string`	AWS-style access key ID
`secretAccessKey`	`string`	AWS-style secret access key

Buckets (Required)

Array of Shelby account addresses (strings) to expose as S3 buckets.

Environment Variables

Variable	Default	Description
`PORT`	`9000`	Server port (overrides config file)
`HTTPS`	-	Set to `true` to enable HTTPS

CLI Options

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

Running with HTTPS

For local development with HTTPS:

# Install mkcert (macOS)
brew install mkcert
mkcert -install

# Generate certificates
mkdir -p certs && cd certs && mkcert localhost

# Run with HTTPS enabled
HTTPS=true npx @shelby-protocol/s3-gateway --config shelby.config.yaml

The gateway will be available at https://localhost:9000.

Advanced: TypeScript Configuration

For dynamic configuration or custom credential/bucket providers, use a shelby.config.ts file:

shelby.config.ts

import { Network } from "@aptos-labs/ts-sdk";
import {
  defineConfig,
  StaticCredentialProvider,
  StaticBucketProvider,
} from "@shelby-protocol/s3-gateway";

export default defineConfig({
  shelby: {
    network: Network.SHELBYNET,
    rpc: {
      baseUrl: "https://api.shelbynet.shelby.xyz/shelby",
    },
  },
  server: {
    port: 9000,
    region: "shelbyland",
  },
  credentialProvider: new StaticCredentialProvider({
    credentials: new Map([
      ["AKIAIOSFODNN7EXAMPLE", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"],
    ]),
  }),
  bucketProvider: new StaticBucketProvider({
    buckets: ["0x0694a79e492d268acf0c6c0b01f42654ac050071a343ebc4226cb6717d63e4ea"],
  }),
});

TypeScript configs require additional setup. You'll need a package.json with "type": "module" and the necessary dependencies installed.

Custom Providers

Implement custom providers for dynamic credential or bucket lookup:

shelby.config.ts

import { defineConfig } from "@shelby-protocol/s3-gateway";
import type { CredentialProvider } from "@shelby-protocol/s3-gateway";

// Custom credential provider (e.g., from database)
class DatabaseCredentialProvider implements CredentialProvider {
  async getCredential(accessKeyId: string) {
    const result = await db.query(
      "SELECT secret_key FROM credentials WHERE access_key_id = ?",
      [accessKeyId]
    );
    return result ? { accessKeyId, secretAccessKey: result.secret_key } : undefined;
  }

  async listAccessKeyIds() {
    const results = await db.query("SELECT access_key_id FROM credentials");
    return results.map((r) => r.access_key_id);
  }

  async refresh() {
    // Refresh cache if needed
  }
}

export default defineConfig({
  shelby: { /* ... */ },
  credentialProvider: new DatabaseCredentialProvider(),
  bucketProvider: new StaticBucketProvider({ buckets: ["0x..."] }),
});

Configuration

On this page