Development Setup

HugBucket requires Python 3.14 or later. Verify your Python version with python --version before continuing.

Prerequisites

Python 3.14+ — required by requires-python = ">=3.14" in pyproject.toml
uv — used for dependency management and running scripts

Setup

Clone the repository

Clone the HugBucket repository and navigate into the project directory.

git clone https://github.com/sachnun/hugbucket
cd hugbucket

Install dependencies

Use uv sync to install all runtime and dev dependencies into a local virtual environment.

uv sync

This installs both the main dependencies (aiohttp, blake3, lz4, pyftpdlib) and the dev group (pytest, boto3, awscli, pytest-asyncio, pytest-aiohttp).

Set your Hugging Face token

HugBucket authenticates against the Hugging Face API using a token. Export it as an environment variable before running the server.

export HF_TOKEN=hf_xxxxx

Get your token from huggingface.co/settings/tokens.

Run the gateway

Start HugBucket in either S3 or FTP mode.

MODE=s3 HF_TOKEN=hf_xxxxx uv run hugbucket

MODE=ftp HF_TOKEN=hf_xxxxx uv run hugbucket

The MODE environment variable selects the protocol. Valid values are s3 and ftp. The server will exit with code 2 if MODE is missing or invalid.

Explicit protocol entrypoints

Instead of setting MODE, you can use the protocol-specific entrypoints defined in pyproject.toml:

pyproject.toml

[project.scripts]
hugbucket     = "hugbucket.main:main"
hugbucket-s3  = "hugbucket.apps.s3:main"
hugbucket-ftp = "hugbucket.apps.ftp:main"

HF_TOKEN=hf_xxxxx uv run hugbucket-s3

HF_TOKEN=hf_xxxxx uv run hugbucket-ftp

Using a protocol-specific entrypoint still requires MODE to match — hugbucket-s3 expects MODE=s3 and hugbucket-ftp expects MODE=ftp. If MODE is set to the wrong value the process exits with code 2.

CLI flags

Both entrypoints accept the same CLI flags via argparse.

S3 gateway (`hugbucket-s3`)

Flag	Default	Description
`--host`	`0.0.0.0`	Bind host
`--port`	`9000`	Bind port
`--verbose`, `-v`	`false`	Enable debug logging

HF_TOKEN=hf_xxxxx uv run hugbucket-s3 --host 127.0.0.1 --port 9090 --verbose

FTP gateway (`hugbucket-ftp`)

Flag	Default	Description
`--host`	`0.0.0.0`	Bind host
`--port`	`2121`	Bind port
`--verbose`, `-v`	`false`	Enable debug logging

HF_TOKEN=hf_xxxxx uv run hugbucket-ftp --host 127.0.0.1 --port 2222 --verbose

When --verbose is set, logging is configured at DEBUG level. Without it, INFO level is used.

Dev dependencies

All dev dependencies are in the [dependency-groups] dev section of pyproject.toml and are installed automatically by uv sync:

pyproject.toml

[dependency-groups]
dev = [
    "awscli>=1.44.55",
    "boto3>=1.42.65",
    "pytest>=8.0",
    "pytest-asyncio>=0.25",
    "pytest-aiohttp>=1.0",
]

Package	Purpose
`pytest`	Test runner
`pytest-asyncio`	`asyncio_mode = "auto"` support for async test functions
`pytest-aiohttp`	aiohttp test client for S3 server integration tests
`boto3`	AWS SDK used in integration tests
`awscli`	CLI tool for manual S3 endpoint testing

Get Started

Deployment

Protocols

Architecture

Development

Prerequisites

Setup

Explicit protocol entrypoints

CLI flags

S3 gateway (`hugbucket-s3`)

FTP gateway (`hugbucket-ftp`)

Dev dependencies

​Prerequisites

​Setup

​Explicit protocol entrypoints

​CLI flags

​S3 gateway (hugbucket-s3)

​FTP gateway (hugbucket-ftp)

​Dev dependencies

Prerequisites

Setup

Explicit protocol entrypoints

CLI flags

S3 gateway (`hugbucket-s3`)

FTP gateway (`hugbucket-ftp`)

Dev dependencies