Skip to content
S3 Lens

Installation

S3 Lens ships as a single binary with the web UI embedded at build time. You can build from source or run a Docker image.

Requirements

Section titled “Requirements”
  • From source: Rust 1.96+, Node.js 24+, and pnpm
  • Docker: Docker with build support

You also need a YAML configuration file (s3lens.yaml) that defines your storage providers. See Configuration and Storage providers.

Build from source

Section titled “Build from source”
Terminal window
git clone https://github.com/luxass/s3lens.git
cd s3lens


sfw pnpm install --ignore-scripts
just build-release

The release binary is at target/release/s3lens.

For a debug build during development:

Terminal window
just build
# or: cargo build

Docker

Section titled “Docker”

Build and run with your config file mounted read-only:

Terminal window
docker build -t s3lens:latest .
docker run --rm -p 8080:8080 \
  -v "$PWD/s3lens.yaml:/app/s3lens.yaml:ro" \
  s3lens:latest --config /app/s3lens.yaml --host 0.0.0.0 --port 8080

For Docker Compose deployment options, see the deployments README in the repository.

Run the server

Section titled “Run the server”
Terminal window
s3lens --config s3lens.yaml --host 127.0.0.1 --port 8080
Flag Description
--config PATH Path to your YAML configuration file
--host HOST Bind address (overrides server.host in config)
--port PORT Listen port (overrides server.port in config)

Open the UI at the host and port you configured — for example http://127.0.0.1:8080.

First-time setup

Section titled “First-time setup”
  1. Copy the example config and environment file:
Terminal window
cp s3lens.yaml.example s3lens.yaml
cp .env.example .env

  1. Edit s3lens.yaml with your provider endpoints and credentials. Use environment variable references (see Configuration) instead of putting secrets directly in the file.

  2. Start S3 Lens and confirm you can list providers and browse buckets in the UI.

Security checklist

Section titled “Security checklist”

Before exposing S3 Lens beyond localhost:

  • Set authentication to enabled: true and connect your identity provider
  • Define access policies so users only reach the providers, buckets, and prefixes they need
  • Set S3LENS_SESSION_SECRET to a random string of at least 32 bytes for session cookie signing
  • Run behind HTTPS (reverse proxy or TLS termination)
  • Keep provider credentials in environment variables or a secrets manager, not in plain text in version control

Auth is disabled by default, which is convenient for local development but must not be used on untrusted networks.