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 vp install --ignore-scripts
pnpm build:release

The release binary is at target/release/s3lens.

For a debug build during development:

Terminal window
pnpm build
# or: cargo build

Desktop app

Section titled “Desktop app”

Run the desktop development shell with:

Terminal window
pnpm dev:desktop

On first launch, open Settings → Workspaces and add either a local Workspace by choosing an existing s3lens.yaml, or a remote Workspace by entering the deployed API origin. Later launches open the last successfully connected Workspace directly. Switch Workspaces from the application sidebar header and switch Providers from the normal top bar. The desktop always supplies its own website assets; a remote deployment only needs to expose a compatible /api and may omit its Web UI.

Local Workspaces are managed processes. Electron starts the Rust server on an ephemeral loopback port and stops it when the Workspace is retired. Remote Workspace authentication opens the system browser and returns to the desktop through a short-lived loopback handoff. For an authenticated imported local Environment, register a loopback redirect pattern that permits an ephemeral port while retaining /api/auth/callback. For the local Keycloak client, use http://127.0.0.1/*.

Build the unsigned host-platform desktop package with:

Terminal window
pnpm package:desktop

macOS is the first packaged acceptance target. Signing, notarization, and Windows/Linux distribution are separate release milestones.

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 8085:8085 \
  -v "$PWD/s3lens.yaml:/app/s3lens.yaml:ro" \
  s3lens:latest --config /app/s3lens.yaml --host 0.0.0.0 --port 8085

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 8085
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:8085.

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.