Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sachnun/hugbucket/llms.txt

Use this file to discover all available pages before exploring further.

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

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.

​
Environment variables

VariableRequiredDescription
MODEYesRun mode: s3 or ftp
HF_TOKENYesHugging Face access token
AWS_ACCESS_KEY_IDS3 onlyS3 access key your client will use
AWS_SECRET_ACCESS_KEYS3 onlyS3 secret key your client will use
FTP_USERNAMEFTP onlyFTP login username
FTP_PASSWORDFTP onlyFTP 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.
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us