nexo

README

Nexo

Self-hosted, S3-compatible object storage in Go, with video streaming and responsive images built in.
One binary: S3 server, Admin API and web console. From one drive to a multi-node cluster.

Quick start · Features · Video · Images · Screenshots · Documentation · Italiano

_{Sign in, a versioned bucket, an upload, a preview and a share link in the web console (recorded with make demo-gif).}

✨ Why Nexo

• One binary, no moving parts. nexo is the S3 server, the Admin API and the web console; there is no external metadata database. The same binary runs on one drive, on several drives with erasure coding, or as a cluster of nodes.
• Really S3. It passes all 451 applicable tests of Ceph's s3-tests and the 638 of MinIO's mint SDK suites, on one drive, several drives and in a cluster: your SDKs, aws, rclone and backup tools just work.
• Your videos play the moment they land. An uploaded MP4 streams as HLS straight away, and a media worker can add every quality from 240p to 4K, a poster and seek-bar thumbnails, with no ffmpeg anywhere.
• Videos that cannot be downloaded, with no DRM vendor. For courses and members' areas: encrypted streams, playback tokens per viewer, a limit on simultaneous streams, a moving watermark with the viewer's name, and the original locked; for more, a Nexo-player-only mode with keys exchanged per session and an invisible forensic watermark that names the source of a leaked copy. One switch in the console (protected videos).
• Every photo in the format and size each screen needs. The same worker turns every uploaded image into AVIF, WebP, JPEG and PNG at every width, and one URL serves the most compact one the browser accepts, on the S3 endpoint or on your own domain.
• Built for operators. A console for everything, Prometheus metrics with a ready-made Grafana dashboard, live traces and logs, and packages for every platform.

Coming from MinIO? Follow the migration guide (every version, policies and users, verified with nexoctl diff). Choosing a store? See how Nexo compares with MinIO, SeaweedFS, Garage and Ceph RGW, including where another project fits better.

🚀 Quick start

Docker docker run -d --name nexo -p 9000:9000 -p 9001:9001 \ -e NEXO_ROOT_USER=admin \ -e NEXO_ROOT_PASSWORD=supersecret \ -v nexo-data:/data paolor/nexo:latest server /data

Binary (releases or make build) export NEXO_ROOT_USER=admin NEXO_ROOT_PASSWORD=supersecret nexo server ~/nexo-data # several drives: nexo server /mnt/disk{1...4}

Open the console at http://localhost:9001 (user admin, password supersecret), or use the CLI:

nexoctl alias set local http://localhost:9000 admin supersecret
nexoctl mb local/photos
nexoctl cp hello.txt local/photos/
nexoctl share download --expire 2h local/photos/hello.txt     # a revocable link

Any S3 client works with the endpoint http://localhost:9000 and the same credentials, for example aws --endpoint-url http://localhost:9000 s3 ls. The images are on Docker Hub: paolor/nexo (server and CLI) and paolor/nexoctl (CLI only).

🧩 Features

🪣 S3 API SigV4, buckets, objects, multipart, versioning, Object Lock, lifecycle, notifications, CORS, checksums, SSE-S3 / SSE-KMS / SSE-C encryption, presigned URLs and POST policies.	🛡️ Durability Reed-Solomon erasure coding with configurable parity, bitrot protection, automatic healing, hot drive replacement, expansion with new pools.
🔐 Security IAM users, groups and policies, access keys with expiry, STS, access rules with glob and regex, revocable share links, TLS with hot reload, mTLS between nodes, built-in KMS or KES, audit log, protected videos. Report a vulnerability: SECURITY.md.	🎬 Video and images MP4 videos stream as HLS packaged on the fly, with revocable stream links and a public player page. The media worker adds renditions, posters and thumbnails (video), and every image in AVIF, WebP, JPEG and PNG at every width (images). Paid content plays encrypted and cannot be downloaded (protected videos).
🌍 Distributions A bucket served on your own domains, CloudFront style: ACME certificates, signed URLs, in-memory and on-disk cache with automatic invalidation.	📈 Operations Web console, Prometheus metrics with Grafana dashboard and alerts, live trace and logs, OpenTelemetry, deb/rpm, Homebrew, Docker images, Helm chart, systemd unit.

🎬 Video, built in

Upload an MP4 and it plays at once, in any browser and any HLS player: Nexo packages the stream on the fly from the file you stored, with no transcoding and nothing to prepare. Share it with a revocable stream link that opens a ready-made player page.

Create the bucket with the HLS video option (or add a media rule to an existing one) and nexo-media-worker derives more from every video it selects: lower qualities for slow networks (240p to 2160p, offered by the same playlist), a poster and the thumbnails of the seek bar. The worker is a separate Go program built on Cisco's OpenH264, no ffmpeg, that works through the S3 API with a least-privilege policy and never loses a job.

Videos that only your users may watch, and nobody may download: see protected videos.

Player: HLS in any browser, with the quality picked for the network	Media panel: poster, timeline thumbnails and renditions of a video
Media rules: which videos and images of a bucket get which outputs	# stream any MP4 through a revocable link nexoctl share download --stream --expire 7d \ local/videos/talk.mp4 # a video bucket: every quality, poster, thumbnails nexoctl mb --with-hls local/videos nexoctl cp intro.mp4 local/videos/ nexoctl media status local/videos/intro.mp4

Job on a 20 s 1080p video (4 vCPU Xeon 2.1 GHz)	Speed
720p + 360p + 240p renditions	3.2× real time (a 10-minute video in about 3 minutes)
one rendition	4–4.5× real time
thumbnails, one per second	74× real time
poster	44 ms

Every job uses all the cores: the video is split at its keyframes and each part is decoded and encoded on its own core, with the same result byte for byte. Details: video streaming, media worker, benchmarks.

🔒 Protected videos

For course platforms, members' areas and paid content: videos your users can watch but not download, with no DRM vendor and no license server. Everything runs inside Nexo, and you switch it on per bucket from the console (bucket → Media → Video protection) or with nexoctl media protection set.

Threat	What Nexo does
Downloading the file	The original is refused to everyone without nexo:DownloadProtectedMedia: S3 GET, copy, select, console, zip archives and distributions
Saving the stream with a downloader	The segments are encrypted (HLS AES-128, a new key every 10 segments); keys are released only at playback pace, so a downloader gets 429 and saves noise
Reading the keys in the browser	Advanced mode (Nexo player only): an ECDH key exchange over a WebSocket, segments encrypted per session (AES-GCM), keys wrapped and kept non-extractable in WebCrypto; standard players and HLS downloaders get nothing
Sharing the link	The link holds a short-lived playback token your application issues per viewer; it expires, it can be revoked per session or per viewer, and keys can be restricted to your site's origin
Sharing the account	At most N simultaneous streams per viewer: a newer stream replaces the oldest one, on every node of a cluster
Recording the screen	Cannot be prevented without commercial DRM: the player draws a moving watermark with the viewer's name or email, so a leaked copy names its source
Cropping the watermark, re-encoding	Forensic watermark: every stream carries an invisible code of its token in the picture (A/B variants per segment); nexoctl media trace reads it from a leaked copy and names the viewer

// your backend (Node.js, Deno, Bun): one token per logged-in viewer
import { createNexoClient } from '@nexo-storage/player/server';
const nexo = createNexoClient({ endpoint: 'https://nexo.example.com:9001', accessKey, secretKey });
const { playlist } = await nexo.issuePlaybackToken({
  bucket: 'lms', key: 'courses/intro.mp4', subject: String(user.id), watermark: user.email,
});

<!-- your page: any HLS player works; this one also draws the watermark -->
<script type="module">
  import { defineNexoPlayer } from 'https://nexo.example.com:9000/nexo/media/sdk/index.js';
  defineNexoPlayer();
</script>
<nexo-player src="PLAYLIST_URL"></nexo-player>

Two levels. In the standard mode no special player is needed: a protected video is standard HLS, playable by Safari, hls.js, Video.js, Shaka, ExoPlayer or VLC with the playlist URL alone. In the advanced mode only the Nexo player plays it (its page, <nexo-player>, createPlayer()), with the same code on your side. The small JavaScript SDK (<nexo-player>, React, Angular, Vue, Node.js backends) covers both. Guide: video protection.

🖼️ Images in every format

Upload a photo once and every screen gets the right file. In an image bucket nexo-media-worker turns each picture into AVIF, WebP, JPEG and PNG at its own size and at every width from 160 to 2560 pixels, and a single URL serves the narrowest variant wide enough in the most compact format the client accepts: AVIF to recent browsers, WebP to the others, JPEG to everyone else. Pure Go, nothing like libvips or ImageMagick to install.

Variants: every format and width of a photo, with their size and a preview

Image buckets: one switch when the bucket is created, or an image rule later

# an image bucket: every photo in AVIF, WebP, JPEG and PNG, at every width
nexoctl mb --with-images local/photos
nexoctl cp beach.jpg local/photos/
nexoctl media status local/photos/beach.jpg

# 640 pixels wide, in the best format the client accepts (a public bucket here:
# otherwise sign the URL or make a share link with nexoctl share download --image)
curl -H 'Accept: image/avif,image/webp' -o beach.avif \
  'http://localhost:9000/nexo/media/v1/photos/image/beach.jpg?w=640'

<!-- the browser picks the width, Nexo picks the format -->
<img src="https://s3.example.com/nexo/media/v1/photos/image/beach.jpg?w=640"
     srcset="https://s3.example.com/nexo/media/v1/photos/image/beach.jpg?w=320 320w,
             https://s3.example.com/nexo/media/v1/photos/image/beach.jpg?w=1280 1280w"
     sizes="(max-width: 700px) 100vw, 640px" alt="The beach">

On your own domain, the same URL serves AVIF, WebP or JPEG. A distribution of an image bucket answers https://cdn.example.com/photos/beach.jpg with the best format for the Accept header of each browser; ?w=640 asks for a width, ?format=webp for a format and ?format=original for the file you uploaded.

Formats	AVIF, WebP, JPEG, PNG (all of them, or those of the rule)
Widths	the image at its own size and 160, 320, 640, 1280, 1920, 2560 px; never enlarged
Sources	JPEG, PNG, GIF, WebP, AVIF, HEIC (iPhone photos), TIFF, BMP, recognized by their content
Variants	upright (EXIF orientation applied), no metadata (no EXIF, GPS or camera data), transparency kept

Job on a 12 MP photo (4 vCPU Xeon 2.1 GHz)	Time
28 variants: 4 formats × its own size and 6 widths	11 s
14 variants, WebP and JPEG only	3 s

The variants are encoded in parallel within a memory budget, and decompression bombs are refused before they are decoded. Details: media worker, benchmarks.

📸 Screenshots

_{The overview of the web console (shown in dark mode when your browser prefers it). The images are taken from a demo deployment with make screenshots; drive capacity is shown as 4 × 1 TiB for illustration.}

Object browser: folders, uploads, versions, previews and share links	Bucket lifecycle: expiration, noncurrent versions and incomplete uploads
IAM policy editor: AWS policy JSON with completion, validation and a visual builder	Access rules: allow and deny by prefix, glob or regex, with conditions
Distributions: buckets served on custom domains, with TLS and traffic	Distribution cache: hit ratio, bandwidth saved and top domains
Monitoring: requests, errors, latency and bandwidth of every node	Cluster: pools, erasure sets, nodes and drives at a glance
Users: IAM users with their policies and groups	Sign in: the console uses the same access keys as the S3 API

⚡ Performance

Measured on a 4 vCPU Xeon virtual machine, with the method and the machine described in docs/bench (make bench and make bench-media measure your own hardware and save its description with the results):

warp, same VM	1 drive	4 drives, EC 2+2	cluster, 4 processes × 2 drives, EC 4+4
PUT 64 MiB objects	727 MiB/s	384 MiB/s	296 MiB/s
GET 64 MiB objects	3.8 GiB/s	2.9 GiB/s	1.4 GiB/s
Mixed workload	4439 op/s	2498 op/s	327 op/s
LIST	61 680 keys/s	18 604 keys/s	7093 keys/s

The cluster row runs four nodes on the same 4 vCPU machine: a real cluster spreads them over machines and networks. Video and image jobs are in the sections video and images.

📚 Documentation

📖 Documentation site: https://r3n3r0.github.io/Nexo/ (Italian: https://r3n3r0.github.io/Nexo/it/), with search, the CLI reference and the Admin API.

The same pages are in docs/user, in English with an Italian translation next to every page (<page>.it.md; also at https://github.com/R3n3r0/Nexo/tree/main/docs/user, for those reading this file from a release archive):

🏁 Quickstart	the complete walkthrough in five minutes
📦 Installation	binaries, deb/rpm, Homebrew, Docker, Compose, Helm, systemd
🗄️ Deployment modes	single drive, multiple drives, cluster, sizing
⚙️ Configuration	flags, environment variables, dynamic configuration
🩺 Operations guide	monitoring, healing, upgrades, backup, troubleshooting
🔐 Security	policies, sharing, access rules, TLS, KMS
🌍 Distributions and cache	custom domains, with a complete tutorial
🎬 Video and images	HLS streaming, stream links and the media worker: renditions, posters, thumbnails and images in every format
🔒 Video protection	encrypted streams, playback tokens, Nexo-player-only mode, visible and forensic watermarks, the JavaScript SDK for web pages and backends
📘 Reference	CLI, Admin API, S3 compatibility

make docs-site publishes it as a static site with MkDocs (in bin/site, in English and in Italian under /it/).

Project documents (architecture, design, roadmap, test plan)

#	Document	Contents
1	Architecture	Components, repository layout, stack, technical choices
2	Features	Catalog of the server, dashboard and CLI features, differences from S3
3	Cluster	Topology, erasure coding, quorum, distributed locks, healing, expansion
4	API	Supported S3 APIs, Admin API, internode RPC
5	Roadmap and tasks	Milestones, tasks with IDs, dependencies and acceptance criteria, status
6	Test plan	Strategy and test cases for server, CLI, dashboard and cluster
7	Security and operations	Threat model, TLS, KMS, observability
8	Modes and release	Deployment modes, packaging and release process
9	Presigned URLs, policies and sharing	Presigned URLs, POST policies, policies, revocable share links
10	Access, domains and distributions	Access rules, domains, distributions behind proxies
11	Per-domain cache	Memory/disk cache, per-level policies, invalidation, cluster cache
12	Service architecture	Binding convention for services, routes and composition in internal/app

The changes of every release are in the CHANGELOG; the test coverage of every feature in the catalog is in the traceability matrix.

🛠️ Development

You need Go (the version in go.mod) and, for the console, Node.js.

Make targets

Command	What it runs
make build	React console and the bin/nexo and bin/nexoctl binaries with the console embedded (make build-go: Go only)
make test / make test-race	Go tests (unit and in-process integration in the three modes)
make test-integration	S3/IAM/presigned integration suite in every mode, slow tests included
make test-cluster	cluster tests with 4 real bin/nexo processes (kill, pause, restart)
make test-s3compat	Ceph s3-tests compatibility suite
make lint / make web-lint / make web-test / make e2e	Go lint, console lint and tests, Playwright
make run-cluster	local cluster of 4 processes with S3 on 127.0.0.1:9101, 9103, 9105, 9107 and the console on the next port (Linux)
make docs / make docs-check	CLI reference in docs/user/cli
make traceability / make traceability-check	feature → test matrix in test/TRACEABILITY.md
make security	govulncheck, gosec and npm audit
make bench / make bench-media	warp benchmarks of the server in every mode / benchmarks of the video and image pipeline (docs/bench)
make build-media-worker / make docker-media-worker	the bin/nexo-media-worker binary / its image
make zap-scan	authenticated OWASP ZAP active scan of the Admin API from api/openapi.yaml against bin/nexo (needs Java; test/security/zap-api-scan.sh)
make screenshots	regenerates the console screenshots in docs/images/screenshots from a seeded demo deployment (Playwright; scripts/screenshots)
make dco	the sign-off check of the pull requests on the commits of the branch (CONTRIBUTING.md)
make help	all the targets

The code follows the convention of docs/12: every service has an interface and an unexported implementation, and composition happens only in internal/app. Contributions are welcome: see CONTRIBUTING.md.

✉️ Contact

Questions, commercial licenses, partnerships: paolorusso1991@gmail.com. Security problems: see SECURITY.md.

📄 License

Nexo is free software licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only): if you modify it and let users interact with it over a network, you must offer them the source code of your version. The NOTICE file adds attribution terms (AGPL section 7(b)): keep it, and keep "Powered by Nexo (https://github.com/R3n3r0/Nexo)" in the legal notices of the user interface. Organizations that cannot comply with the AGPL can buy a commercial license from the copyright holder; contributions are accepted under the terms of CONTRIBUTING.md. Archives, deb/rpm packages, container images and the Helm chart carry LICENSE (and NOTICE in archives and packages).