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

# Quick Start

> Get HugBucket running in minutes with Docker

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

<CardGroup cols={2}>
  <Card title="Docker" icon="docker" href="https://docs.docker.com/get-docker/">
    Required to run HugBucket from the pre-built image. Install Docker Desktop or Docker Engine before continuing.
  </Card>

  <Card title="Hugging Face token" icon="key" href="https://huggingface.co/settings/tokens">
    A Hugging Face access token (`HF_TOKEN`). Generate one from your HF account settings with read/write access to your buckets.
  </Card>
</CardGroup>

## Run HugBucket

<Tabs>
  <Tab title="S3 mode">
    <Steps>
      <Step title="Start the container">
        Pull and run the HugBucket image with S3 mode enabled. Replace `hf_xxxxx` with your real Hugging Face token.

        ```bash theme={null}
        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
        ```

        <Note>
          `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.
        </Note>
      </Step>

      <Step title="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.

        ```bash theme={null}
        aws --endpoint-url http://localhost:9000 s3 ls
        aws --endpoint-url http://localhost:9000 s3 cp file.txt s3://my-bucket/file.txt
        ```

        <Tip>
          Add `--endpoint-url http://localhost:9000` to any `aws s3` or `aws s3api` command to route it through HugBucket.
        </Tip>
      </Step>
    </Steps>
  </Tab>

  <Tab title="FTP mode">
    <Steps>
      <Step title="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.

        ```bash theme={null}
        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
        ```

        <Warning>
          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.
        </Warning>
      </Step>

      <Step title="Connect with an FTP client">
        Use any FTP client to connect to port `2121` on localhost.

        ```bash theme={null}
        ftp localhost 2121
        # username: hugbucket
        # password: hugbucket
        ```

        <Note>
          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`.
        </Note>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 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](https://docs.astral.sh/uv/) and use the commands below.

<Steps>
  <Step title="Install dependencies">
    ```bash theme={null}
    uv sync
    ```
  </Step>

  <Step title="Start the gateway">
    Use the unified entrypoint with `MODE`, or call a protocol-specific entrypoint directly.

    <CodeGroup>
      ```bash Unified entrypoint theme={null}
      MODE=s3 HF_TOKEN=hf_xxxxx uv run hugbucket
      ```

      ```bash S3 entrypoint theme={null}
      HF_TOKEN=hf_xxxxx uv run hugbucket-s3
      ```

      ```bash FTP entrypoint theme={null}
      HF_TOKEN=hf_xxxxx uv run hugbucket-ftp
      ```
    </CodeGroup>

    <Note>
      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.
    </Note>
  </Step>
</Steps>


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