Quick Start

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
FTP mode

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.

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.

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.

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.

Install dependencies

uv sync

Start the gateway

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

MODE=s3 HF_TOKEN=hf_xxxxx uv run hugbucket

HF_TOKEN=hf_xxxxx uv run hugbucket-s3

HF_TOKEN=hf_xxxxx uv run hugbucket-ftp

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.

Get Started

Deployment

Protocols

Architecture

Development

Prerequisites

Docker

Hugging Face token

Run HugBucket

Environment variables

Development mode

​Prerequisites

Docker

Hugging Face token

​Run HugBucket

​Environment variables

​Development mode

Prerequisites

Run HugBucket

Environment variables

Development mode