# AList User Guide

**AList** is a self-hosted file list program that puts dozens of cloud drives, object stores, and network protocols behind a single web interface. Point it at your Aliyundrive, OneDrive, Google Drive, S3 bucket, local disk, SMB share — over 90 storage backends in all — and AList presents them as one browsable, searchable file tree that you can preview, download, upload to, and even re-share over WebDAV, FTP, SFTP, or an S3-compatible endpoint.

It is a single Go binary (powered by the Gin web framework and a Solid.js front end). There is no database server to install, no runtime to provision: download one executable (or pull one Docker image), run it, and open your browser.

> [!NOTE]
> This guide covers **using and operating** AList day to day: installing it, mounting storages, browsing and sharing files, and the access protocols. For architecture, the full configuration reference, deployment hardening, the driver-development model, and internals, see the **AList Admin Guide**.

---

## 1. Quick Start

The fastest path from zero to a working file list is three commands. Pick the binary or the Docker route.

=== "Binary (Linux/macOS)"

    ```bash
    # 1. Download and extract the release for your platform, then run:
    ./alist server
    ```

    ```text
    INFO[0000] reading config file: data/config.json
    INFO[0000] config file not exists, creating default config file
    INFO[0000] Successfully created the admin user and the initial password is: a1b2c3d4
    INFO[0000] start HTTP server @ 0.0.0.0:5244
    ```

=== "Docker"

    ```bash
    docker run -d \
      --name alist \
      -p 5244:5244 \
      -v ./alist-data:/opt/alist/data \
      --restart unless-stopped \
      xhofe/alist:latest
    ```

    ```bash
    # Read the auto-generated admin password from the container logs:
    docker logs alist 2>&1 | grep password
    ```

Then:

1. Open **`http://<your-server-ip>:5244`** in a browser.
2. Click **Login** (top-right) and sign in as **`admin`** with the password printed in the startup log.
3. Go to the **management panel** at **`http://<your-server-ip>:5244/@manage`**.
4. Open **Storages → Add**, choose a driver (e.g. `Local`, `Onedrive`, `S3`), fill in its fields, and save.
5. Return to the home page — your storage now appears as a folder under its mount path.

> [!IMPORTANT]
> The initial admin password is shown **only once**, in the first-run log. AList stores it as a hash and cannot print it again. If you miss it, reset it with `./alist admin set <new-password>` (binary) or `docker exec -it alist ./alist admin set <new-password>` (Docker). See [Managing the admin account](#62-managing-the-admin-account).

> [!TIP]
> AList listens on **0.0.0.0:5244** by default — reachable from any machine on your network. Before exposing it to the internet, read [Securing your instance](#9-securing-your-instance).

---

## 2. What AList Does

AList sits between you and your storage providers. You mount each provider once (with its credentials), and AList gives every mounted backend a uniform interface:

```text
        Browser / WebDAV client / FTP client / S3 SDK / AI assistant (MCP)
                                  │
                                  ▼
                          ┌───────────────┐
                          │     AList      │   one mount tree: /onedrive, /s3, /local …
                          └───────────────┘
              ┌──────────────┬──────┴───────┬──────────────┐
              ▼              ▼              ▼              ▼
         OneDrive      Aliyundrive       S3 bucket     Local disk   … 90+ backends
```

What you can do with a mounted tree:

- **Browse and preview** — folders, images (gallery mode), video and audio (with subtitles and lyrics), PDFs, Office documents, Markdown, code, and plain text, all in the browser.
- **Download** — single files, or whole folders as an archive; copy permanent direct links.
- **Upload, create, rename, move, copy, delete** — including moving or copying files *between two different storages* (e.g. OneDrive → S3).
- **Offline download** — hand a magnet link or URL to aria2, qBittorrent, Transmission, or a built-in HTTP downloader and have the result land directly in a cloud storage.
- **Search** — across your mounted tree, optionally backed by a full-text index.
- **Share and re-serve** — expose the tree (or a sub-path) over **WebDAV**, **FTP/SFTP**, or an **S3-compatible** endpoint, or create password-protected public **share links**.
- **Protect** — per-path passwords, hidden files, signed links, and role-based permissions for multiple users.
- **Connect AI assistants** — an optional **MCP server** lets tools like Claude Desktop list, read, and manage files.

> [!NOTE]
> AList is a *front end* to storage you already own. It does not store your files itself — it proxies or redirects to the underlying provider. The only local state AList keeps is its configuration, the storage list, users, and (optionally) a search index. See the Admin Guide for the data model.

---

## 3. Installation

### 3.1 Requirements

AList ships as a statically-linked binary, so requirements are minimal.

| Resource | Requirement |
|---|---|
| OS | Linux, macOS, Windows, FreeBSD (any platform Go targets) |
| Architecture | amd64, arm64, arm, 386, and more (per release assets) |
| Disk | A few MB for the binary + space for `data/` (config, DB, optional index) |
| Network | One open TCP port (default `5244`) |
| Dependencies | **None** — no external database, runtime, or libraries required |

> [!TIP]
> By default AList uses an embedded **SQLite** database stored inside `data/`. You do not need to install or run a database server. MySQL and PostgreSQL are optional alternatives covered in the Admin Guide.

### 3.2 Install methods

=== "Pre-built binary"

    1. Download the archive for your OS/arch from the project's releases.
    2. Extract it to a directory you control:

       ```bash
       mkdir -p /opt/alist && cd /opt/alist
       tar -zxvf alist-linux-amd64.tar.gz
       ```

    3. Make it executable and run:

       ```bash
       chmod +x alist
       ./alist server
       ```

=== "Docker"

    ```bash
    docker run -d \
      --name alist \
      -p 5244:5244 \
      -v ./alist-data:/opt/alist/data \
      --restart unless-stopped \
      xhofe/alist:latest
    ```

    The image exposes ports **5244** and **5245** and stores all state in the volume **`/opt/alist/data`**.

=== "Docker Compose"

    ```yaml
    services:
      alist:
        image: xhofe/alist:latest
        container_name: alist
        ports:
          - "5244:5244"
        volumes:
          - "./alist-data:/opt/alist/data"
        restart: unless-stopped
    ```

    ```bash
    docker compose up -d
    ```

> [!CAUTION]
> Always bind-mount **`/opt/alist/data`** (Docker) or preserve the **`data/`** directory (binary). It holds your configuration, your storage list, your users, and the JWT secret. Losing it means re-configuring every storage from scratch.

### 3.3 First run

On the very first `alist server`, AList:

1. Creates `data/config.json` with sensible defaults.
2. Creates the **`admin`** user with a **random** initial password and prints it to the log:

   ```text
   Successfully created the admin user and the initial password is: <random>
   ```

3. Starts the HTTP server on `0.0.0.0:5244`.

Capture that password immediately, or reset it (next section).

---

## 4. Running AList

AList is a single command with sub-commands. The main one is `server`.

### 4.1 Starting and stopping

| Action | Command | Notes |
|---|---|---|
| Start in foreground | `./alist server` | Runs attached; `Ctrl+C` stops it gracefully |
| Start as background daemon | `./alist start` | Detaches, writes a PID file under `daemon/` |
| Stop the daemon | `./alist stop` | Terminates the daemon by its PID file |
| Restart the daemon | `./alist restart` | Equivalent to `stop` then `start` |
| Force-kill the daemon | `./alist kill` | Sends `SIGKILL` via the PID file (last resort) |

```bash
# Typical foreground run with a custom data directory:
./alist server --data /var/lib/alist
```

```text
INFO[0000] reading config file: /var/lib/alist/config.json
INFO[0000] start HTTP server @ 0.0.0.0:5244
```

> [!NOTE]
> On Windows, `./alist stop` behaves the same as `kill` (there is no Unix-signal daemon). Use a service manager (NSSM, Task Scheduler) for unattended Windows operation.

> [!TIP]
> For real production use, run AList under a process supervisor — `systemd`, Docker's `--restart`, or similar — rather than the built-in `start`/`stop` daemon. The Admin Guide has a ready-to-use systemd unit.

### 4.2 Global flags

These flags work on `server` and most sub-commands:

| Flag | Default | Purpose |
|---|---|---|
| `--data <dir>` | `data` | Directory for config, database, logs, temp, and index |
| `--debug` | `false` | Verbose logging and Gin debug mode |
| `--dev` | `false` | Developer mode (debug routes enabled) |
| `--force-bin-dir` | `false` | Resolve `--data` relative to the binary's own location |
| `--log-std` | `false` | Always log to stdout (not just the log file) |
| `--no-prefix` | `false` | Read environment-variable overrides **without** the `ALIST_` prefix |

```bash
./alist server --data ./data --debug --log-std
```

### 4.3 The `version` command

```bash
./alist version
```

```text
Built At: ...
Go Version: go1.25.0 linux/amd64
Author: Xhofe <[email removed]>
Commit ID: d0cec67
Version: v3.x.x
WebVersion: ...
```

---

## 5. Mounting Storages

A **storage** is one mounted backend: a driver plus the credentials and options it needs, attached at a **mount path** like `/onedrive` or `/photos/family`.

### 5.1 Adding a storage

1. Log in as `admin` and open the management panel (`/@manage`).
2. Go to **Storages** → **Add**.
3. Choose a **Driver** from the dropdown (see the [catalog](#53-storage-driver-catalog)).
4. Set the **Mount path** — where this storage appears in your tree (e.g. `/cloud/onedrive`).
5. Fill in the **driver-specific fields** (tokens, keys, root folder, region, …). Each field has inline help.
6. Set any **common options** (cache, sort order, proxy mode — see [common settings](#52-common-storage-settings)).
7. **Save.** AList initializes the driver and, if successful, the mount appears on the home page.

> [!TIP]
> Many cloud drivers (Aliyundrive, OneDrive, Google Drive, 115, …) authenticate with OAuth tokens or cookies rather than a username/password. The field help text and the official documentation at **alistgo.com** walk through obtaining each one. AList only stores what you paste in.

> [!IMPORTANT]
> A storage's **mount path** must be unique. Mounting two storages at the same path is not allowed. Use nested paths (`/a`, `/a/b`) freely — AList resolves the most specific match.

### 5.2 Common storage settings

Every storage, regardless of driver, exposes this shared set of options:

| Setting | Meaning |
|---|---|
| **Mount path** | Where the storage appears in the file tree (must be unique) |
| **Order** | Sort weight among sibling storages on the home page |
| **Remark** | A free-text note for your own reference |
| **Cache expiration** | Minutes to cache directory listings before re-fetching from the backend |
| **Web proxy** | Stream downloads *through* AList instead of redirecting the browser to the backend |
| **WebDAV policy** | How WebDAV serves files: native, `302_redirect`, or `use_proxy_url` |
| **Down proxy URL** | An external proxy/CDN URL to hand out for direct downloads |
| **Enable sign** | Require a signature on direct links for this storage |
| **Disable index** | Exclude this storage from the search index |
| **Order by / direction** | Default sort field and direction for listings |
| **Extract folder** | Put files from the front or back when flattening |
| **Disabled** | Temporarily turn the storage off without deleting it |

> [!NOTE]
> **Proxy vs. redirect.** For many cloud drives AList can hand the browser a temporary direct link from the provider (fast, no AList bandwidth). Some drivers *must* proxy (their links are IP- or header-locked); those are marked internally as proxy-only. Enable **Web proxy** when you want every download to flow through AList — e.g. to apply a single public URL, add speed limits, or hide the backend.

### 5.3 Storage driver catalog

AList ships **90+ storage drivers**. You only configure the ones you use. They fall into these families:

**Mainstream cloud drives**

| Driver | Backend |
|---|---|
| `Onedrive`, `OnedriveAPP`, `Onedrive Sharelink` | Microsoft OneDrive / SharePoint |
| `GoogleDrive`, `GooglePhoto` | Google Drive, Google Photos |
| `Dropbox` | Dropbox |
| `YandexDisk` | Yandex Disk |
| `Mega_nz` | MEGA |
| `pCloud` | pCloud |
| `Seafile` | Seafile server |

**Chinese cloud drives**

| Driver | Backend |
|---|---|
| `Aliyundrive`, `AliyundriveOpen`, `AliyundriveShare` | Alibaba Cloud Drive |
| `BaiduNetdisk`, `BaiduPhoto`, `BaiduShare`, `BaiduYouth` | Baidu Netdisk family |
| `115 Cloud`, `115 Open`, `115 Share` | 115 |
| `123Pan`, `123 Open`, `123PanLink`, `123PanShare` | 123Pan |
| `Quark`, `QuarkTV`, `UC`, `UCTV` | Quark / UC Drive |
| `Thunder`, `ThunderX`, `ThunderBrowser`, `ThunderExpert`, … | Xunlei / Thunder |
| `189Cloud`, `189CloudPC` | China Telecom 189 |
| `139Yun` | China Mobile 139 |
| `PikPak`, `PikPakShare` | PikPak |
| `Terabox` | Terabox |
| `Lanzou`, `ILanZou`, `FeijiPan` | Lanzou family |
| `Quqi`, `WoPan`, `MoPan`, `WeiYun`, `Teambition`, `MediaTrack`, `Doubao`, `DoubaoShare`, `ChaoXingGroupDrive`, `VTencent`, `BitQiu`, `GuangYaPan`, `LenovoNasShare`, `HalalCloud`, `WuKongNetdisk`, `Trainbit`, `NeteaseMusic`, `Misskey`, `Lark`, `KodBox`, `Gofile`, `MediaFire`, `Streamtape`, `Darkibox`, `FebBox`, `Doge`, `360AIYunPan`, … | Other regional / niche drives |

**Object storage & network protocols**

| Driver | Backend |
|---|---|
| `S3` | Amazon S3 and S3-compatible stores |
| `Azure Blob Storage` | Microsoft Azure Blob |
| `USS` | UPYUN Storage Service |
| `FTP`, `FTPS` | FTP / FTPS servers |
| `SFTP` | SFTP servers |
| `SMB` | SMB/CIFS network shares |
| `WebDav` | Any WebDAV server (incl. OneDrive/SharePoint without API) |
| `IPFS API` | IPFS node |
| `Local` | A directory on the AList host's own disk |

**Other AList servers & developer integrations**

| Driver | Backend |
|---|---|
| `AList V2`, `AList V3` | Another AList instance (federation) |
| `GitHub API`, `GitHub Releases`, `Gitee` | Git hosting as a file tree |
| `ProtonDrive` | Proton Drive |
| `Cloudreve`, `Cloudreve V4` | Cloudreve servers |

**Virtual / meta drivers** — these wrap *other* mounted storages rather than talking to an external provider:

| Driver | What it does |
|---|---|
| `Alias` | Merge several existing mount paths into one virtual folder |
| `Crypt` | Transparently encrypt/decrypt another storage (rclone-crypt compatible) |
| `Chunker` | Split large files into chunks across a backend that has size limits |
| `Strm` | Generate `.strm` files pointing at media, for Emby/Jellyfin/Plex |
| `UrlTree` | Build a file tree from a list of URLs you supply |
| `Virtual` | An in-memory tree for testing |
| `Template` | The starting point for writing your own driver (developers) |

> [!TIP]
> The exact field list for each driver is shown in the Add-Storage form and documented at **alistgo.com**. The catalog above tells you *which driver to pick*; the form tells you *what to fill in*.

### 5.4 Editing, disabling, and removing storages

- **Edit** — change credentials or options at any time; AList re-initializes the driver on save.
- **Disable** — toggle a storage off (it disappears from the tree but keeps its config). From the CLI: `./alist storage disable <mount-path>`.
- **Delete** — remove the storage and its configuration permanently.
- **List from the CLI** — `./alist storage list` opens an interactive table of every storage (ID, driver, mount path, enabled).

```bash
# Inspect storages without opening the web UI:
./alist storage list

# Disable a misbehaving mount quickly:
./alist storage disable /onedrive
```

---

## 6. Everyday Usage

### 6.1 Browsing, previewing, and downloading

From the home page you navigate the merged tree like any file browser:

- **Click a folder** to open it; **click a file** to preview it.
- **Images** open in a gallery with next/previous navigation.
- **Video and audio** stream in-browser, with subtitle and lyric support.
- **Documents** (PDF, Office, Markdown, code, text) render inline.
- **Download** a file with the download button, or select a folder and download it as a package.
- **Copy direct link / permalink** to share a stable URL to a single file.

Direct download URLs follow simple patterns you can use in scripts:

| URL pattern | Serves |
|---|---|
| `/d/<path>` | Direct download (may redirect to the backend) |
| `/p/<path>` | Proxied download (always streamed through AList) |
| `/s/<share_id>` | A public share page |

> [!TIP]
> Append a download to any path to fetch it with `curl`/`wget`. If the storage has **Enable sign** on, the link includes a `?sign=` token — copy the full signed URL from the UI.

### 6.2 Managing the admin account

The `admin` account is special — it always exists and always has full permissions. Manage it from the CLI:

| Command | Effect |
|---|---|
| `./alist admin` | Show the admin username (and reset hints) |
| `./alist admin random` | Set the admin password to a new random string and print it |
| `./alist admin set <password>` | Set the admin password to a value you choose |
| `./alist admin token` | Print the admin API token |
| `./alist cancel2fa` | Remove two-factor authentication from the admin account |

```bash
# Forgot the admin password? Set a known one:
./alist admin set 'My$tr0ngPass'
```

```text
INFO admin user has been updated:
INFO username: admin
INFO password: My$tr0ngPass
```

> [!WARNING]
> Anyone with shell access to the AList host can reset the admin password with `alist admin set`. Treat host access as equivalent to full AList admin access, and protect the `data/` directory accordingly.

### 6.3 Users, roles, and per-path permissions

Beyond `admin`, you can create additional users (management panel → **Users**) and assign them **roles**. Each role grants a set of fine-grained permissions, optionally scoped to specific paths.

The permission set AList enforces:

| Permission | Allows the user to… |
|---|---|
| See hidden files | View files matched by hide rules |
| Access without password | Skip per-path password prompts |
| Add offline download | Queue offline-download tasks |
| Write | Upload / create |
| Rename | Rename items |
| Move | Move items |
| Copy | Copy items |
| Remove | Delete items |
| WebDAV read | Read over WebDAV |
| WebDAV manage | Write/modify over WebDAV |
| FTP access | Connect over FTP/SFTP |
| FTP manage | Modify over FTP/SFTP |
| Read archives | Browse inside archives |
| Decompress | Extract archives |
| Path limit | Restrict the user to a base path subtree |
| MCP access | Use the MCP server (read) |
| MCP manage | Use the MCP server (write) |

A built-in **guest** user controls what anonymous (not-logged-in) visitors can do. Disable it to require login for everything.

> [!NOTE]
> Permissions are evaluated **per path**. A role can grant *read* everywhere but *write* only under `/uploads`, for example. The Admin Guide covers role configuration and the permission model in depth.

### 6.4 Hiding and password-protecting paths (Meta)

**Meta** rules attach behavior to a path and its children, configured under management → **Metas**:

- **Password** — require a password to enter a folder.
- **Hide** — hide files matching a regex from listings.
- **Readme** — show a README on a folder page.
- **Write** — allow guest uploads into a specific folder.

> [!TIP]
> Meta rules cascade. Set a password on `/private` and every subfolder inherits it unless you add a more specific rule. Combine **Hide** with the *See hidden files* permission to keep files out of the public listing but visible to trusted users.

---

## 7. Sharing Files

### 7.1 Public share links

Create a share (management → **Shares**, or the share action on a file/folder) to hand out a link that does **not** require an AList account:

- Optional **password** protection.
- Optional **expiry**.
- Scoped to a single file or a whole sub-tree.

Share URLs use the `/s/<share_id>` (browse), `/sd/<share_id>` (download), and `/sp/<share_id>` (proxy) patterns.

### 7.2 WebDAV access

AList re-serves your whole tree over **WebDAV** at the **`/dav`** path — mount it in Windows Explorer, macOS Finder, or apps like RaiDrive, Kodi, or Infuse.

```text
URL:      http://<host>:5244/dav
Username: <your AList username>
Password: <your AList password>
```

> [!NOTE]
> WebDAV honors the same permissions as the web UI (via the *WebDAV read* / *WebDAV manage* permissions). The `admin` account can also authenticate over WebDAV using its API token as a Bearer credential.

### 7.3 FTP, SFTP, and S3 endpoints

AList can additionally expose your tree as:

- An **FTP / FTPS** server (default `:5221`) — for legacy clients and appliances.
- An **SFTP** server (default `:5222`) — password or SSH-public-key auth.
- An **S3-compatible** endpoint (default `:5246`) — point any S3 SDK or tool at it.

These are **off by default** and are enabled in `config.json` (see the Admin Guide). FTP/SFTP access requires the *FTP access* permission on the user.

```bash
# Once SFTP is enabled, connect with any SSH client:
sftp -P 5222 admin@<host>
```

### 7.4 Connecting an AI assistant (MCP)

AList includes a **Model Context Protocol (MCP)** server so AI assistants (Claude Desktop, and other MCP clients) can list, read, and manage your files as tools.

- **HTTP mode** — enable the MCP server in `config.json` (default port `5248`); clients connect over Streamable HTTP.
- **STDIO mode** — run `./alist mcp --user admin` to serve a single session over standard input/output, ideal for desktop assistant integrations.

```bash
# Launch an MCP STDIO session acting as the admin user:
./alist mcp --user admin
```

> [!IMPORTANT]
> MCP access is gated by the *MCP access* / *MCP manage* permissions and requires authentication. Only give MCP-manage to assistants you trust to modify files.

---

## 8. Power Features

### 8.1 Copying files between storages

Select a file or folder in one storage and **copy** or **move** it into another — AList streams the data between backends for you (e.g. pull a file from a friend's shared Aliyundrive into your own S3 bucket). Large transfers run as background **tasks** you can monitor, retry, or cancel under management → **Tasks**.

### 8.2 Offline download

Hand AList a URL or magnet link and let a download engine fetch it **directly into a cloud storage**, without routing the bytes through your own machine. Supported engines:

| Engine | Use for |
|---|---|
| **aria2** | HTTP/FTP/BitTorrent, via an aria2 RPC endpoint |
| **qBittorrent** | BitTorrent, via the qBittorrent Web API |
| **Transmission** | BitTorrent, via the Transmission RPC |
| **SimpleHttp** | Plain HTTP(S) downloads, built in (no external tool) |
| **115 / PikPak / Thunder / GuangYaPan** | Each drive's own native offline-download (cloud-side fetch) |

Configure the engine's connection details under management → **Settings**, then use the **offline download** action on a destination folder.

> [!TIP]
> Native cloud offline-download (115, PikPak, Thunder) is usually fastest — the provider fetches the torrent on its own servers and the result appears in your drive with no transfer to AList at all.

### 8.3 Search

Use the search box to find files across your mounted tree. AList offers three search backends (set in the Admin settings):

- **Database (default)** — indexes file metadata in AList's own database; lightweight.
- **Bleve** — an embedded full-text index, no external service.
- **Meilisearch** — an external Meilisearch instance for large libraries and fast full-text search.

For indexed search, build the index once from management → **Settings → Index**, then keep it current (manually or via auto-update). You can exclude individual storages from indexing with **Disable index**.

### 8.4 Archive preview and extraction

AList can look *inside* archives (`.zip`, `.7z`, `.rar`, `.iso`, and more) without extracting them — browse the contents, preview a file, or extract to a destination — subject to the *Read archives* and *Decompress* permissions. Archive direct-access URLs use the `/ad/`, `/ap/`, and `/ae/` patterns.

### 8.5 Encryption, chunking, and media (.strm)

These virtual drivers transform another storage:

- **Crypt** — wrap any backend so files are encrypted at rest and decrypted on the fly (compatible with rclone's crypt). Mount the encrypted backend, then mount `Crypt` on top of it.
- **Chunker** — split oversized files into pieces so they fit a backend's per-file size limit, transparently reassembled on download.
- **Strm** — generate `.strm` pointer files for a media library so Emby/Jellyfin/Plex can stream from your cloud storage.

---

## 9. Securing Your Instance

AList defaults are convenient, not locked-down. Before exposing it publicly, do at least the following:

- [ ] **Reset the admin password** to a strong value: `./alist admin set <strong-password>`.
- [ ] **Enable 2FA** on the admin account (management → Profile).
- [ ] **Put AList behind HTTPS** — a reverse proxy (Caddy, Nginx, Traefik) is the easiest path; AList can also terminate TLS itself (see Admin Guide).
- [ ] **Restrict the guest user** or disable anonymous access entirely.
- [ ] **Tighten CORS** — the default allows all origins (`*`); narrow it in `config.json` for a public deployment.
- [ ] **Lock down the `data/` directory** — it contains the JWT secret and all credentials.
- [ ] **Leave TLS verification ON** — do **not** set `tls_insecure_skip_verify`; AList warns loudly that doing so exposes all storage traffic to interception.

> [!CAUTION]
> Disabling TLS certificate verification (`tls_insecure_skip_verify`) makes every connection AList opens to your storage providers vulnerable to man-in-the-middle attacks, which can leak credentials or tamper with your data. AList prints an explicit security warning when it is on. Only use it if you fully understand the risk.

> [!NOTE]
> The full hardening checklist, TLS setup, reverse-proxy examples, sign/secret rotation, and the complete config reference are in the **AList Admin Guide → Security**.

---

## 10. Troubleshooting

### Error: `config file not exists, creating default config file`

**Cause:** First run, or the `data/` directory was moved/deleted.
**Solution:** This is informational on first start. If it appears unexpectedly, you launched AList with the wrong `--data` path — point it back at your real data directory.
**Prevention:** Always pass the same `--data` (or keep the working directory consistent); bind-mount `/opt/alist/data` in Docker.

### I missed the initial admin password

**Cause:** The random password is logged only once, at first start.
**Solution:** Set a new one: `./alist admin set <password>` (or `./alist admin random` to generate one).
**Prevention:** Capture the first-run log, or reset to a known value immediately after install.

### Error: `start HTTP server` never appears / port already in use

**Cause:** Another process is bound to `5244`, or the HTTP port is disabled in config.
**Solution:** Free the port, or change `scheme.http_port` in `config.json`. Confirm `http_port` is not set to `-1` (which disables HTTP).
**Prevention:** Decide your port up front and reverse-proxy onto it.

### A storage shows an error / red status after saving

**Cause:** Bad credentials, an expired token, or the backend is unreachable.
**Solution:** Edit the storage and re-enter the token/cookie; check the **Status** message on the storage row for the driver's specific error. For OAuth drivers, re-run the token-acquisition flow.
**Prevention:** Refresh tokens before they expire; some drivers refresh automatically once initialized.

### Mounting Tencent Weiyun causes a crash / nil pointer

**Cause:** A known issue with the Weiyun driver under certain accounts (community issue #9551).
**Solution:** Disable the Weiyun storage (`./alist storage disable <path>`) to restore service, and track the upstream issue for a fix.
**Prevention:** Test new cloud drivers on a non-critical instance before relying on them.

### `failed to list objs: PROPFIND /: 400` on a WebDAV-backed storage

**Cause:** The upstream WebDAV server rejected the listing request (community issue #7771) — often a wrong root path or an incompatible server.
**Solution:** Verify the WebDAV URL and root folder; some servers need the path with or without a trailing slash. Try toggling proxy mode.
**Prevention:** Confirm the WebDAV endpoint works in a standalone client first.

### Copying a large file between two cloud drives runs out of memory

**Cause:** Some cross-drive copies buffer aggressively (community issue #9374).
**Solution:** Enable **Web proxy** with range support on the source storage, lower the relevant task concurrency in Settings, or use native offline-download where available.
**Prevention:** Prefer same-provider operations or native cloud transfers for very large files.

### WebDAV / FTP login is refused

**Cause:** The user lacks the *WebDAV read* (or *FTP access*) permission, or the protocol is disabled in config.
**Solution:** Grant the relevant permission to the user's role; confirm FTP/SFTP is enabled in `config.json`. For admin-over-WebDAV, use the API token as a Bearer credential.
**Prevention:** Map out which users need which protocols when you create roles.

### Files appear twice when using Alias + indexed search

**Cause:** An `Alias` storage and its underlying storages are both indexed (community issue #9489).
**Solution:** Set **Disable index** on either the alias or the underlying mounts so each file is indexed once.
**Prevention:** Decide a single canonical mount for indexing when you use Alias.

---

## 11. FAQ

**Q: Does AList store my files?**
No. AList is a front end to storage you already own. It proxies or redirects to the underlying provider; the only local state is configuration, the storage/user list, and an optional search index.

**Q: Do I need a database server?**
No. AList uses an embedded SQLite database inside `data/` by default. MySQL/PostgreSQL are optional (Admin Guide).

**Q: How many storages can I mount?**
There is no fixed limit — mount as many as you need, including multiple accounts of the same provider at different paths.

**Q: Can two storages share a mount path?**
No — mount paths are unique. Use nested paths, or an `Alias` driver to merge several into one virtual folder.

**Q: How do I reset the admin password?**
`./alist admin set <password>`, or `./alist admin random` for a generated one. Requires shell access to the host.

**Q: What's the default port?**
HTTP on **5244**. HTTPS, FTP (`:5221`), SFTP (`:5222`), S3 (`:5246`), and MCP (`:5248`) are off by default and enabled in config.

**Q: Can I run AList behind a reverse proxy with a sub-path?**
Yes. Set `site_url` to the public base URL (including any sub-path); AList adjusts its routes and links accordingly. See the Admin Guide.

**Q: How do I let visitors upload without an account?**
Add a **Meta** rule with *write* enabled on a specific folder, and grant the guest user the *Write* permission there. Scope it tightly.

**Q: Can AI assistants use AList?**
Yes — enable the MCP server (HTTP mode) or run `./alist mcp` (STDIO mode) and connect an MCP client like Claude Desktop. Access is permission-gated.

**Q: Does AList support encrypted storage?**
Yes — the `Crypt` driver encrypts/decrypts another backend transparently and is compatible with rclone's crypt format.

**Q: How do I download a whole folder?**
Select the folder and use package download, or use the `/d/<path>` URL pattern per file in a script.

**Q: Where does the search index live?**
Database search uses AList's own DB. Bleve stores an index under `data/`. Meilisearch runs as a separate external service you point AList at.

**Q: Is there an API?**
Yes — AList exposes a full REST API (the web UI is built on it). Endpoints, auth, and the admin API are documented in the Admin Guide; public API reference is also published by the project.

**Q: How do I update AList?**
Replace the binary (or pull a new Docker image) and restart. Your `data/` directory carries forward; AList migrates its config and database on startup.

---

## 12. Command Reference

| Command | Purpose |
|---|---|
| `alist server` | Start the server (HTTP + any enabled protocols) |
| `alist start` | Start as a background daemon |
| `alist stop` | Stop the daemon |
| `alist restart` | Restart the daemon |
| `alist kill` | Force-kill the daemon by PID file |
| `alist admin` | Show admin username and reset hints |
| `alist admin random` | Reset admin password to a random string |
| `alist admin set <pw>` | Set the admin password |
| `alist admin token` | Print the admin API token |
| `alist cancel2fa` | Remove 2FA from the admin account |
| `alist storage list` | Interactive table of all storages |
| `alist storage disable <path>` | Disable a storage by mount path |
| `alist mcp [--user <name>]` | Start the MCP server in STDIO mode |
| `alist lang` | (Developer) generate language JSON files |
| `alist version` | Print version and build info |

**Default ports**

| Service | Port | Default state |
|---|---|---|
| HTTP | `5244` | On |
| HTTPS | — | Off (`-1`) |
| FTP | `5221` | Off |
| SFTP | `5222` | Off |
| S3 | `5246` | Off |
| MCP | `5248` | Off |

**Direct-link URL patterns**

| Pattern | Serves |
|---|---|
| `/d/<path>` | Direct download (may redirect to backend) |
| `/p/<path>` | Proxied download (always through AList) |
| `/s/<share_id>` | Public share page |
| `/sd/<share_id>` | Public share download |
| `/dav` | WebDAV endpoint |

---

_Generated June 2026 from AlistGo/alist at d0cec67. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._