Skip to main content

​
Overview

HugBucket exposes a standard FTP server backed by Hugging Face Storage Buckets. FTP clients connect to port 2121 and navigate a virtual filesystem where the top-level directories correspond to buckets and paths within them map to object keys. Path mapping: /<bucket>/<key> For example, the FTP path /my-bucket/data/file.csv maps to the object key data/file.csv in the bucket my-bucket.

​
Port configuration

Passive mode uses ports 30000–30099. When running in Docker, you must expose the full range: -p 30000-30099:30000-30099. When running behind a firewall or NAT, these ports must be forwarded to the host.

​
Authentication

Credentials are configured via environment variables: Both variables must be set together. If both are left empty, anonymous FTP login is allowed.
Leaving both FTP_USERNAME and FTP_PASSWORD empty enables anonymous access. Any client can connect without credentials. Only use this in trusted, isolated environments.
You cannot set only one of FTP_USERNAME or FTP_PASSWORD — both must be provided or both must be empty. Starting the server with only one set will fail with a configuration error.

​
Starting the server

​
Connecting

1

Open an FTP connection

Connect to port 2121 on your host:
2

Authenticate

Enter the username and password you configured with FTP_USERNAME and FTP_PASSWORD:
For anonymous access (when both variables are empty), enter anonymous as the username.
3

Enable passive mode

Most FTP clients default to passive mode. If your client requires it explicitly, run:
Data connections will use a port in the range 30000–30099.
4

Navigate and transfer files

The root directory / lists all buckets. Change into a bucket directory to access its objects:

​
Supported FTP operations

The HugBucketFTPFilesystem class implements the following FTP commands:
chmod and readlink are not supported and will return a permission or OS error if invoked.

​
Path mapping

The FTP virtual filesystem maps directly onto the /{bucket}/{key} hierarchy: Paths are normalized: trailing slashes, ., and .. segments are resolved before being sent to the backend.

​
Passive mode

HugBucket configures passive data ports in the range 30000–30099 (100 ports). Each FTP data transfer (upload, download, or directory listing) opens one port from this range for the duration of the transfer.
If you are running HugBucket behind a reverse proxy, load balancer, or NAT gateway, the full port range 30000–30099 must be forwarded or exposed. Failure to do so will cause directory listings and file transfers to hang or time out in passive mode.