> ## 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

> Multi-protocol gateway for Hugging Face Storage Buckets — access your HF data via S3 or FTP.

## Get started

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Run HugBucket with Docker in two commands and verify with the AWS CLI.
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/deployment/docker">
    Full deployment guide with port mapping, Docker Compose, and auth configuration.
  </Card>

  <Card title="S3 Protocol" icon="server" href="/protocols/s3">
    Complete S3 REST API reference with AWS CLI and boto3 examples.
  </Card>

  <Card title="FTP Protocol" icon="folder" href="/protocols/ftp">
    FTP gateway reference with path mapping and passive port configuration.
  </Card>
</CardGroup>

## What is HugBucket?

HugBucket is a self-hosted gateway that exposes Hugging Face Storage Buckets over standard S3 and FTP protocols. Any tool that speaks S3 — AWS CLI, boto3, rclone, S3 Browser — or FTP can read and write directly to your Hugging Face data without any code changes.

Under the hood, HugBucket implements the full **Xet content-addressable storage** protocol in pure Python: Gearhash content-defined chunking, BLAKE3 hashing, LZ4 compression, and parallel xorb uploads. Data written through HugBucket is fully compatible with the `huggingface_hub` Python library and the HF web UI.

## Key features

<CardGroup cols={2}>
  <Card title="S3-compatible API" icon="aws">
    Full S3 REST API on port 9000. Works with AWS CLI, boto3, rclone, and any S3-compatible client.
  </Card>

  <Card title="FTP gateway" icon="network-wired">
    Standard FTP on port 2121 with `/<bucket>/<key>` path mapping. Useful for legacy tools.
  </Card>

  <Card title="Native Xet storage" icon="database">
    Pure Python Xet CAS: CDC chunking, BLAKE3 hashing, LZ4 compression — compatible with `huggingface_hub`.
  </Card>

  <Card title="Docker-first" icon="docker">
    Single image, one `MODE` variable. Switch between S3 and FTP by changing one environment variable.
  </Card>

  <Card title="Streaming + range requests" icon="arrow-down">
    HTTP range requests for `GetObject` with CDN-level skip of irrelevant xorb chunks.
  </Card>

  <Card title="Multipart uploads" icon="upload">
    S3 multipart upload with idempotent completion and automatic stale-upload cleanup.
  </Card>

  <Card title="Server-side copy" icon="copy">
    `CopyObject` reuses the existing content hash — no bytes are re-downloaded or re-uploaded.
  </Card>

  <Card title="Built-in caching" icon="bolt">
    LRU caches for xorb chunks (512 MiB), file metadata, and reconstruction plans.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.