flow/docs/versioned_docs/version-1.9.0/Develop/concepts-file-management.mdx

---
title: Manage files
slug: /concepts-file-management
---

import Icon from "@site/src/components/icon";

Each Hanzo Flow server has a file management system where you can store files that you want to use in your flows.

Files uploaded to Hanzo Flow file management are stored in Hanzo Flow's [storage backend (local or AWS S3)](/concepts-file-management#configure-file-storage), and they are available to all of your flows.

Uploading files to Hanzo Flow file management keeps your files in a central location, and allows you to reuse files across flows without repeated manual uploads.

## Use the file management UI

You can use the file management UI to upload files from your local machine to your own Hanzo Flow server.
You can also manage all files that have been uploaded to your Hanzo Flow server.

1. Navigate to Hanzo Flow file management:

    * **Hanzo Flow Desktop**: In Hanzo Flow, on the [**Projects** page](/concepts-flows#projects) page, click **My Files** below the list of projects.
    * **Hanzo Flow OSS**: From a browser, navigate to your Hanzo Flow server's `/files` endpoint, such as `http://localhost:7860/files`. Modify the base URL as needed for your Hanzo Flow server.
    * **Backend-only**: For programmatic file management, use the [Hanzo Flow API files endpoints](/api-files). However, the following steps assume you're using the file management UI.

2. On the **My Files** page, click **Upload**.

3. Select one or more files to upload.

After uploading files, you can rename, download, copy, or delete files within the file management UI.
To delete a file, hover over a file's icon, select it, and then click <Icon name="Trash2" aria-hidden="true"/> **Delete**.
You can delete multiple files in a single action.
To download a file, hover over a file's icon, select it, and then click <Icon name="Download" aria-hidden="true"/> **Download**.
If you download multiple files in a single action, they are saved together in a zip file.

## Upload and manage files with the Hanzo Flow API

With the Hanzo Flow API, you can upload and manage files in Hanzo Flow file management, and you can send files to flows programmatically at runtime.

For more information and examples, see [Files endpoints](/api-files) and [Create a chatbot that can ingest files](/chat-with-files).

## Set the maximum file size

By default, the maximum file size is 1024 MB.
To modify this value, change the `FLOW_MAX_FILE_SIZE_UPLOAD` [environment variable](/environment-variables).

## Use files in a flow

To use files in your Hanzo Flow file management system in a flow, add a component that accepts file input to your flow, such as the **Read File** component.

For example, add a **Read File** component to your flow, click **Select files**, and then select files from the **My Files** list.

This list includes all files in your server's file management system, but you can only select [file types that are supported by the **Read File** component](/read-file).
If you need another file type, you must use a different component that supports that file type, or you need to convert it to a supported type before uploading it.

For more information about the **Read File** component and other data loading components, see the [**Read file** component](/read-file).

### Load files at runtime

You can use preloaded files in your flows, and you can load files at runtime, if your flow accepts file input.
To enable file input in your flow, do the following:

1. Add a [**Read File** component](/read-file) to your flow.

2. Click **Share**, select **API access**, and then click **Input Schema** to add [`tweaks`](/concepts-publish#input-schema) to the request payload in the flow's automatically generated code snippets.

3. Expand the **File** section, find the **Files** row, and then enable **Expose Input** to allow the parameter to be set at runtime through the Hanzo Flow API.

4. Close the **Input Schema** pane to return to the **API access** pane.
The payload in each code snippet now includes `tweaks` with your **Read File** component's ID and the `path` key that you enabled in **Input Schema**:

    ```json
    "tweaks": {
	    "File-qYD5w": {
		    "path": []
	    }
	}
    ```

5. When you run this flow programmatically, your script must upload a file to Hanzo Flow file management, and then pass the returned `file_path` to the `path` tweak in the `/run` request:

    ```json
    "tweaks": {
        "FILE_COMPONENT_ID": {
            "path": [ "file_path" ]
        }
    }
    ```

    For a complete example see [Create a chatbot that can ingest files](/chat-with-files) and [Files endpoints](/api-files).

    If you want to upload multiple files, you can pass multiple `file_path` values in the `path` array, such as `[ "path1", "path2" ]`.

## Upload images

Hanzo Flow supports base64 images in the following formats:

* PNG
* JPG/JPEG
* GIF
* BMP
* WebP

You can upload images to the **Playground** chat interface and as runtime input with the Hanzo Flow API.

* In the **Playground**, you can drag-and-drop images into the chat input area, or you can click the **Attach image** icon to select an image to upload.

* When you trigger a flow with the `/v1/run/$FLOW_ID` endpoint, you can use the `files` parameter to attach image data as a base64-encoded string:

   ```bash
   curl -X POST "http://$FLOW_SERVER_ADDRESS/v1/run/$FLOW_ID" \
   -H "Content-Type: application/json" \
   -H "x-api-key: $FLOW_API_KEY" \
   -d '{
      "session_id": "custom_session_123",
      "input_value": "What is in this image?",
      "input_type": "chat",
      "output_type": "chat",
      "files": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."]
   }'
   ```

For more specialized image processing, browse <Icon name="Blocks" aria-hidden="true" /> [**Bundles**] or [create your own components](/components-custom-components).

## Work with video files

For videos, see the **Twelve Labs** and **YouTube** <Icon name="Blocks" aria-hidden="true" /> [**Bundles**](/components-bundle-components).

## Configure file storage

Hanzo Flow supports two storage backends for file management.

* **Local storage**: Hanzo Flow's default storage backend. Files are stored locally in your [Hanzo Flow configuration directory](/memory). Set `FLOW_STORAGE_TYPE=local` or leave it unset to use local storage.

* **S3 storage**: Files are stored in an AWS S3 bucket.
Hanzo Flow uses the [boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) library to interact with S3.

To use S3 as your file storage backend, add the following configuration to your `.env` file:

```text
# S3 Storage Configuration
FLOW_STORAGE_TYPE=s3
FLOW_OBJECT_STORAGE_BUCKET_NAME=S3_BUCKET_NAME
FLOW_OBJECT_STORAGE_PREFIX=S3_BUCKET_DIRECTORY

# AWS Credentials (required for S3)
AWS_ACCESS_KEY_ID=S3_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=S3_ACCESS_SECRET_KEY
AWS_DEFAULT_REGION=S3_REGION
```

Replace the following placeholders with the actual values for your S3 instance:

* `S3_BUCKET_NAME`: The name of your S3 bucket.
* `S3_BUCKET_DIRECTORY`: An optional folder path within the bucket where files are stored, such as `s3://S3_BUCKET_NAME/S3_BUCKET_DIRECTORY`.
* `S3_ACCESS_KEY`: Your AWS Access Key ID.
* `S3_ACCESS_SECRET_KEY`: Your AWS Secret Access Key.
* `S3_REGION`: The AWS region where your bucket is located, such as `us-east-2`.

Your AWS credentials must have the necessary permissions to perform the required S3 operations for your use case, such as reading, writing, and deleting files in S3.
This example policy allows basic CRUD operations on S3 objects.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Hanzo FlowS3StorageAccess",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:PutObjectTagging",
            ],
            "Resource": [
                "arn:aws:s3:::S3_BUCKET_NAME",
                "arn:aws:s3:::S3_BUCKET_NAME/S3_BUCKET_DIRECTORY/*"
            ]
        }
    ]
}
```

Replace the following placeholders with the actual values for your IAM policy and S3 instance:

* `S3_BUCKET_NAME`: The name of your S3 bucket.
* `S3_BUCKET_DIRECTORY`: An optional folder path within the bucket where files are stored, such as `s3://S3_BUCKET_NAME/S3_BUCKET_DIRECTORY`.

For more information, see the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html).

**Google Drive** storage is available through the [**Read File**](/read-file) and [**Write file**](/write-file) components, but you cannot use environment variables to configure it.

## File storage environment variables {#file-storage-environment-variables}

The following environment variables configure file storage backends for Hanzo Flow's file management system:

| Variable | Format | Default | Description |
|----------|--------|---------|-------------|
| `FLOW_STORAGE_TYPE` | String | `local` | Set the file storage backend. Supported values: `local` (files stored in the Hanzo Flow configuration directory) or `s3` (files stored in AWS S3). For S3 storage, you must also configure AWS credentials and bucket settings. |
| `FLOW_OBJECT_STORAGE_BUCKET_NAME` | String | Not set | The name of the S3 bucket to use for file storage. Required when `FLOW_STORAGE_TYPE=s3`. |
| `FLOW_OBJECT_STORAGE_PREFIX` | String | Not set | Optional prefix/folder path within the S3 bucket where files will be stored. If not set, files are stored at the bucket root. |
| `FLOW_OBJECT_STORAGE_TAGS` | JSON object | Not set | Optional S3 object tags applied to stored files when `FLOW_STORAGE_TYPE=s3`. Ignored for local storage. Provided as a JSON map of string keys to string values, such as `{"env": "prod", "owner": "data-team"}`. |

## See also

* [Components reference](/concepts-components)