selfhost.directory

The index of self-hostable projects — ranked, categorized and served with live updates.
Own your data and stop giving it to big tech.

BoxBox logo

Self-host BoxBox

v0.3.1

Modern self-hosted file manager for homelab

BetaOpen SourceMIT
Updated10 hours ago
LanguageGo
Setup difficultyModerate
Stars
346
RAM
128M reservation, 512M limit
Port
8080 (HTTP server)
Docker
ghcr.io/jr4dh3y/boxbox
Install with Docker
Browsing a photos folder in grid viewImage preview dialogEditing docker-compose.yml in the code editorShare dialog for a folderPublic share page showing a shared folder

What is BoxBox?

BoxBox runs as a single Go binary with an embedded SvelteKit frontend, deployed via Docker Compose from a published GHCR image. It serves a browser UI for configured Linux mount points, supporting chunked resumable uploads that preserve folder structure, previews for images, audio, video, PDFs, and documents, and a Monaco-based code editor. Users can create expiring share links with four access levels, download folders as ZIP archives, and run copy, move, or delete operations as background jobs with live progress updates over WebSocket. The UI separates storage roots (Drives) from folder shortcuts (Places) and can auto-discover mounted drives. Configuration covers read-only mounts, user accounts with bcrypt passwords, rate limits, and WebSocket origin allow-lists. No external database or cache is required; persistent data lives in a container volume.

Should you self-host BoxBox?

BoxBox scores 48/100 on selfhost.directory (how scoring works) and ranks #21 of 34 in File Management. It has 346 GitHub stars.

It shipped 14 stable releases in the past year. The latest, v0.3.1, came out on 12 October 2026. New versions land roughly every 3 days.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is MIT-licensed and written mostly in Go.

Its closest alternative on selfhost.directory is AList (83/100, 50 365 stars). It scores higher overall, so compare the two before you pick. See BoxBox vs AList side by side.

Features

  • Auto-discovery of drives
  • Background file operations
  • Chunked resumable uploads
  • Code Editor
  • Drive and Places navigation
  • File and folder sharing
  • File Previews
  • Media streaming
  • Multi-mount browsing
  • Read-only mounts
  • REST API
  • Search
  • Wallpaper customization
  • Zip Downloads

BoxBox README

How to install BoxBox

Install BoxBox with Docker

Environment variables
BOXBOX_JWT_SECRET, BOXBOX_USERS_admin

docker run -d
--name boxbox
--restart unless-stopped
--user 10001:10001
-p 8080:8080
-e BOXBOX_JWT_SECRET="$(openssl rand -base64 32)"
-e BOXBOX_USERS_admin='paste-a-bcrypt-hash-here'
-v "$PWD/config.yaml:/app/config.yaml:ro"
-v "$HOME:/home/user"
-v boxbox-data:/data
-v boxbox-temp:/tmp/boxbox
ghcr.io/jr4dh3y/boxbox:v0.3.1

Alternative simple local container without Compose

How to configure BoxBox

  • BOXBOX_ALLOWED_ORIGINSAllowed origins for WebSocket connections

    Allowed origins for WebSocket connections

    values: comma-separated list, supports wildcards

  • BOXBOX_IMAGEghcr.io/jr4dh3y/boxbox:v0.3.1Container image used by docker-compose.yml

    Container image used by docker-compose.yml

    values: image reference

  • BOXBOX_JWT_SECRETJWT signing secret of at least 32 bytes

    JWT signing secret of at least 32 bytes

    values: long random string

  • BOXBOX_RATE_LIMIT_RPS2Auth endpoint rate limit (requests per second per IP)

    Auth endpoint rate limit (requests per second per IP)

    values: integer, 0 to disable

  • BOXBOX_TRUSTED_PROXIESProxy IPs/CIDRs allowed to supply X-Forwarded-For/X-Real-IP

    Proxy IPs/CIDRs allowed to supply X-Forwarded-For/X-Real-IP

    values: comma-separated CIDRs

  • BOXBOX_USERS_adminBcrypt password hash for admin user

    Bcrypt password hash for admin user

    values: bcrypt hash

  • chunk_size_mb10Chunk size in MiB for browser uploads

    Chunk size in MiB for browser uploads

    values: integer

  • DESKTOP_PATHCustom host path for Desktop sidebar shortcut

    Custom host path for Desktop sidebar shortcut

    values: absolute path

  • DOCUMENTS_PATHCustom host path for Documents sidebar shortcut

    Custom host path for Documents sidebar shortcut

    values: absolute path

  • DOWNLOADS_PATHCustom host path for Downloads sidebar shortcut

    Custom host path for Downloads sidebar shortcut

    values: absolute path

  • HOME_PATHHost home directory to expose as /home/user in the container

    Host home directory to expose as /home/user in the container

    values: absolute path

  • host0.0.0.0Bind address

    Bind address

    values: IP address

  • HOST_PORT8080Host port published by docker-compose.yml

    Host port published by docker-compose.yml

    values: port number

  • jwt_secretJWT authentication secret

    JWT authentication secret

    values: long random string

  • max_upload_mb10240Maximum upload size in MiB

    Maximum upload size in MiB

    values: integer

  • mount_pointsDirectories accessible through the file manager

    Directories accessible through the file manager

    values: array of mount point objects

  • MUSIC_PATHCustom host path for Music sidebar shortcut

    Custom host path for Music sidebar shortcut

    values: absolute path

  • PGID10001Group ID mapping for file permissions

    Group ID mapping for file permissions

    values: GID

  • PICTURES_PATHCustom host path for Pictures sidebar shortcut

    Custom host path for Pictures sidebar shortcut

    values: absolute path

  • port8080HTTP port inside the container or process

    HTTP port inside the container or process

    values: port number

  • PUID10001User ID mapping for file permissions

    User ID mapping for file permissions

    values: UID

  • rate_limit_rps2Auth endpoint rate limit per client IP

    Auth endpoint rate limit per client IP

    values: integer

  • usersMap of username to bcrypt hash

    Map of username to bcrypt hash

    values: username: bcrypt hash

  • VIDEOS_PATHCustom host path for Videos sidebar shortcut

    Custom host path for Videos sidebar shortcut

    values: absolute path

BoxBox releases & version history

More in File Management

Rate this project

Click to rate — no account needed.

0 comments

Posting as guest
Loading comments…