Configuration

S3 Lens is configured through a YAML file, typically s3lens.yaml. Copy s3lens.yaml.example as a starting point.

Overview

A minimal config needs a server section and at least one provider:

server:
  host: "127.0.0.1"
  port: 8080

providers:
  - name: "my-storage"
    endpoint: "https://s3.example.com"
    region: "us-east-1"
    path_style: true
    credentials:
      access_key_id: "${S3_ACCESS_KEY_ID}"
      secret_access_key: "${S3_SECRET_ACCESS_KEY}"

Optional top-level sections:

Section	Purpose
server	HTTP bind address and port
providers	S3-compatible storage backends
policy	Authorization policy documents
roles	Named bundles of policies
auth	Login, OIDC, and identity-to-role mapping

See Authentication and Access policies for the security sections.

Server

server:
  host: "127.0.0.1"   # default
  port: 8080          # default

Command-line flags --host and --port override these values.

Providers

Each entry under providers defines one S3-compatible backend. The name is how the UI and API refer to it — for example /api/providers/my-storage/buckets.

Generic S3-compatible providers

Use type: generic or omit type for self-hosted and third-party S3-compatible endpoints (Garage, SeaweedFS, MinIO, Hetzner, AWS, and most others):

providers:
  - name: "garage"
    type: generic
    endpoint: "http://127.0.0.1:3900"
    region: "garage"
    path_style: true
    credentials:
      access_key_id: "${GARAGE_ACCESS_KEY_ID}"
      secret_access_key: "${GARAGE_SECRET_ACCESS_KEY}"

Field	Required	Description
name	Yes	Unique identifier used in URLs and policies
endpoint	Yes	S3 API base URL
region	No	AWS region string (defaults to us-east-1)
path_style	No	Use path-style URLs (true for most self-hosted providers)
credentials.access_key_id	Yes	S3 access key
credentials.secret_access_key	Yes	S3 secret key
credentials.session_token	No	Temporary session token, if applicable

Provider credentials need storage-side permissions for the operations S3 Lens performs (list, read, write, delete). See Provider credentials and permissions.

Provider-specific setup notes: Storage providers.

Google Cloud Storage

GCS uses type: gcp with HMAC keys. See the GCS section for full details.

providers:
  - name: "gcp"
    type: gcp
    project_id: "${GCS_PROJECT_ID}"
    endpoint: "https://storage.googleapis.com"
    region: "auto"
    path_style: true
    credentials:
      access_key_id: "${GCS_ACCESS_KEY_ID}"
      secret_access_key: "${GCS_SECRET_ACCESS_KEY}"

Provider management

Providers are defined only in the config file. There is no API to create, update, or delete providers at runtime — restart S3 Lens after changing provider entries.

API responses never include raw credentials. Listing providers shows redacted summaries only.

Environment variable interpolation

Reference secrets and environment-specific values in YAML:

Syntax	Meaning
${VAR}	Required — error if unset
${VAR:-}	Optional — defaults to empty string
${VAR:-value}	Optional — defaults to value

Example:

credentials:
  access_key_id: "${AWS_ACCESS_KEY_ID}"
  secret_access_key: "${AWS_SECRET_ACCESS_KEY}"

Load variables from a .env file or your deployment platform before starting S3 Lens.

Session secret

When authentication is enabled, set S3LENS_SESSION_SECRET to a random string of at least 32 bytes. This signs session cookies. If unset, S3 Lens generates an ephemeral secret at startup — sessions will not survive restarts and this is unsuitable for production.

Example configurations

The repository includes s3lens.yaml.example with:

• Local Garage and SeaweedFS providers
• OIDC auth wired for the Docker Compose Keycloak profile
• Sample custom policies and roles (garage-readonly, uploads-prefix, deny-presign, and others)

Use it as a reference; keep your working s3lens.yaml out of version control.