Quick Start

Get HugBucket running in minutes with Docker

HugBucket is a multi-protocol gateway that exposes Hugging Face Storage Buckets over S3 and FTP. Pick the protocol that fits your toolchain and have it running in minutes.

Prerequisites

Docker

Required to run HugBucket from the pre-built image. Install Docker Desktop or Docker Engine before continuing.

Hugging Face token

A Hugging Face access token (HF_TOKEN). Generate one from your HF account settings with read/write access to your buckets.

Run HugBucket

S3 mode

1. Start the container

   Pull and run the HugBucket image with S3 mode enabled. Replace hf_xxxxx with your real Hugging Face token.

   docker run -d \
     -p 9000:9000 \
     -e MODE=s3 \
     -e HF_TOKEN=hf_xxxxx \
     -e AWS_ACCESS_KEY_ID=hugbucket \
     -e AWS_SECRET_ACCESS_KEY=hugbucket \
     ghcr.io/sachnun/hugbucket
   

   AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are the credentials your S3 client will use to authenticate with HugBucket — they are not your AWS credentials. Set them to any value you choose and use the same values in your S3 client configuration.

2. Verify with AWS CLI

   Once the container is up, point the AWS CLI at the local endpoint to list your Hugging Face buckets and upload a file.

   aws --endpoint-url http://localhost:9000 s3 ls
   aws --endpoint-url http://localhost:9000 s3 cp file.txt s3://my-bucket/file.txt
   

   Add --endpoint-url http://localhost:9000 to any aws s3 or aws s3api command to route it through HugBucket.

FTP mode

1. Start the container

   FTP requires a command-and-control port plus a passive port range for data transfers. Replace hf_xxxxx with your real Hugging Face token.

   docker run -d \
     -p 2121:2121 \
     -p 30000-30099:30000-30099 \
     -e MODE=ftp \
     -e HF_TOKEN=hf_xxxxx \
     -e FTP_USERNAME=hugbucket \
     -e FTP_PASSWORD=hugbucket \
     ghcr.io/sachnun/hugbucket
   

   You must publish the full passive port range (30000-30099) so that FTP data connections can be established. Omitting these ports will cause directory listings and file transfers to hang.

2. Connect with an FTP client

   Use any FTP client to connect to port 2121 on localhost.

   ftp localhost 2121
   # username: hugbucket
   # password: hugbucket
   

   Paths follow the pattern /<bucket>/<key>. For example, /my-bucket/data/file.txt maps to the key data/file.txt in the bucket my-bucket.

Environment variables

Variable	Required	Description
MODE	Yes	Run mode: s3 or ftp
HF_TOKEN	Yes	Hugging Face access token
AWS_ACCESS_KEY_ID	S3 only	S3 access key your client will use
AWS_SECRET_ACCESS_KEY	S3 only	S3 secret key your client will use
FTP_USERNAME	FTP only	FTP login username
FTP_PASSWORD	FTP only	FTP login password

Development mode

To run HugBucket from source, install uv and use the commands below.

1. Install dependencies

   uv sync
   
2. Start the gateway

   Use the unified entrypoint with MODE, or call a protocol-specific entrypoint directly.

   Unified entrypoint

   MODE=s3 HF_TOKEN=hf_xxxxx uv run hugbucket
   

   The protocol-specific entrypoints (hugbucket-s3, hugbucket-ftp) still require the MODE environment variable to match the protocol. Using hugbucket-s3 without MODE=s3 will exit with an error.